diff options
| author | Pavan Deolasee | 2017-06-14 05:42:18 +0000 |
|---|---|---|
| committer | Pavan Deolasee | 2017-06-14 05:42:18 +0000 |
| commit | 15dd5274c323fb93e4e3ea9ad2185aaaec10f79c (patch) | |
| tree | 9dafb4c7f735d9429ea461dc792933af87493c33 /doc/src | |
| parent | dfbb88e3bbb526dcb204b456b9e5cfd9d10d0d0a (diff) | |
| parent | d5cb3bab564e0927ffac7c8729eacf181a12dd40 (diff) | |
Merge from PG master upto d5cb3bab564e0927ffac7c8729eacf181a12dd40
This is the result of the "git merge remotes/PGSQL/master" upto the said commit
point. We have done some basic analysis, fixed compilation problems etc, but
bulk of the logical problems in conflict resolution etc will be handled by
subsequent commits.
Diffstat (limited to 'doc/src')
225 files changed, 30511 insertions, 10667 deletions
diff --git a/doc/src/sgml/.gitignore b/doc/src/sgml/.gitignore index 2f0329c15f..a72b7ccb06 100644 --- a/doc/src/sgml/.gitignore +++ b/doc/src/sgml/.gitignore @@ -16,14 +16,9 @@ /features-unsupported.sgml /errcodes-table.sgml /version.sgml -/bookindex.sgml -/HTML.index # Assorted byproducts from building the above /postgres.xml /INSTALL.html -/postgres-US.aux -/postgres-US.log -/postgres-US.out -/postgres-A4.aux -/postgres-A4.log -/postgres-A4.out +/INSTALL.xml +/postgres-US.fo +/postgres-A4.fo diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index 22ef50b899..21dfaaf832 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -33,9 +33,10 @@ ifndef DBTOEPUB DBTOEPUB = $(missing) dbtoepub endif -ifndef JADE -JADE = $(missing) jade +ifndef FOP +FOP = $(missing) fop endif + SGMLINCLUDE = -D . -D $(srcdir) ifndef NSGMLS @@ -57,18 +58,11 @@ endif override XSLTPROCFLAGS += --stringparam pg.version '$(VERSION)' -GENERATED_SGML = bookindex.sgml version.sgml \ +GENERATED_SGML = version.sgml \ features-supported.sgml features-unsupported.sgml errcodes-table.sgml ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML) -# Sometimes we don't want this one. -ALMOSTALLSGML := $(filter-out %bookindex.sgml,$(ALLSGML)) - -ifdef DOCBOOKSTYLE -CATALOG = -c $(DOCBOOKSTYLE)/catalog -endif - # Enable some extra warnings # -wfully-tagged needed to throw a warning on missing tags # for older tool chains, 2007-08-31 @@ -77,6 +71,7 @@ endif # noisy to turn on by default, unfortunately. override SPFLAGS += -wall -wno-unused-param -wno-empty -wfully-tagged + ## ## Man pages ## @@ -90,50 +85,9 @@ man-stamp: stylesheet-man.xsl postgres.xml ## -## HTML +## common files ## -.PHONY: draft - -JADE.html.call = $(JADE) $(JADEFLAGS) $(SPFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t sgml -i output-html -ifeq ($(STYLE),website) -JADE.html.call += -V website-stylesheet -endif - -# The draft target creates HTML output in draft mode, without index (for faster build). -draft: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl - $(MKDIR_P) html - $(JADE.html.call) -V draft-mode $< - cp $(srcdir)/stylesheet.css html/ - -html: html-stamp - -html-stamp: postgres.sgml $(ALLSGML) stylesheet.dsl - $(MAKE) check-tabs - $(MKDIR_P) html - $(JADE.html.call) -i include-index $< - cp $(srcdir)/stylesheet.css html/ - touch $@ - -# single-page HTML -postgres.html: postgres.sgml $(ALLSGML) stylesheet.dsl - $(JADE.html.call) -V nochunks -V rootchunk -V '(define %root-filename% #f)' -V '(define use-output-dir #f)' -i include-index $< - -# single-page text -postgres.txt: postgres.html - $(LYNX) -force_html -dump -nolist $< > $@ - -HTML.index: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl - @$(MKDIR_P) html - $(JADE.html.call) -V html-index $< - -bookindex.sgml: HTML.index -ifdef COLLATEINDEX - LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g -i 'bookindex' -o $@ $< -else - @$(missing) collateindex.pl $< $@ -endif - # Technically, this should depend on Makefile.global, but then # version.sgml would need to be rebuilt after every configure run, # even in distribution tarballs. So this is cheating a bit, but it @@ -154,73 +108,11 @@ features-unsupported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_package errcodes-table.sgml: $(top_srcdir)/src/backend/utils/errcodes.txt generate-errcodes-table.pl $(PERL) $(srcdir)/generate-errcodes-table.pl $< > $@ -## -## Print -## - - -# RTF to allow minor editing for hardcopy -%.rtf: %.sgml $(ALLSGML) - $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t rtf -V rtf-backend -i output-print -i include-index postgres.sgml - -# TeX -# Regular TeX and pdfTeX have slightly differing requirements, so we -# need to distinguish the path we're taking. - -JADE.tex.call = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d $(srcdir)/stylesheet.dsl -t tex -V tex-backend -i output-print -i include-index - -%-A4.tex-ps: %.sgml $(ALLSGML) - $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=A4 -o $@ $< - -%-US.tex-ps: %.sgml $(ALLSGML) - $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=USletter -o $@ $< - -%-A4.tex-pdf: %.sgml $(ALLSGML) - $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=A4 -o $@ $< - -%-US.tex-pdf: %.sgml $(ALLSGML) - $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=USletter -o $@ $< - -%.dvi: %.tex-ps - @rm -f $*.aux $*.log -# multiple runs are necessary to create proper intra-document links - jadetex $< - jadetex $< - jadetex $< - -# PostScript from TeX -postgres.ps: - $(error Invalid target; use postgres-A4.ps or postgres-US.ps as targets) - -%.ps: %.dvi - dvips -o $@ $< - -postgres.pdf: - $(error Invalid target; use postgres-A4.pdf or postgres-US.pdf as targets) - -%.pdf: %.tex-pdf - @rm -f $*.aux $*.log $*.out -# multiple runs are necessary to create proper intra-document links - pdfjadetex $< - pdfjadetex $< - pdfjadetex $< - -# Cancel built-in suffix rules, interfering with PS building -.SUFFIXES: - - -# This generates an XML version of the flow-object tree. It's useful -# for debugging DSSSL code, and possibly to interface to some other -# tools that can make use of this. -%.fot: %.sgml $(ALLSGML) - $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t fot -i output-print -i include-index -o $@ $< - ## -## Semi-automatic generation of some text files. +## Generation of some text files. ## -JADE.text = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -i output-text -t sgml ICONV = iconv LYNX = lynx @@ -233,34 +125,47 @@ LYNX = lynx # locale support and is very picky about locale name spelling. The # below has been finely tuned to run on FreeBSD and Linux/glibc. INSTALL: % : %.html - $(PERL) -p -e 's/<H(1|2)$$/<H\1 align=center/g' $< | LC_ALL=en_US.ISO8859-1 $(LYNX) -force_html -dump -nolist -stdin | $(ICONV) -f latin1 -t us-ascii//TRANSLIT > $@ + $(PERL) -p -e 's,<h(1|2) class="title",<h\1 align=center,g' $< | LC_ALL=en_US.ISO8859-1 $(LYNX) -force_html -dump -nolist -stdin | $(ICONV) -f latin1 -t us-ascii//TRANSLIT > $@ -INSTALL.html: standalone-install.sgml installation.sgml version.sgml - $(JADE.text) -V nochunks standalone-install.sgml installation.sgml > $@ +INSTALL.html: %.html : stylesheet-text.xsl %.xml + $(XMLLINT) --noout --valid $*.xml + $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ >$@ + +INSTALL.xml: standalone-install.sgml installation.sgml version.sgml + $(OSX) $(SPFLAGS) $(SGMLINCLUDE) -x lower $(filter-out version.sgml,$^) >[email protected] + $(call mangle-xml,chapter) ## -## XSLT processing +## SGML->XML conversion ## # For obscure reasons, GNU make 3.81 complains about circular dependencies # if we try to do "make all" in a VPATH build without the explicit # $(srcdir) on the postgres.sgml dependency in this rule. GNU make bug? -postgres.xml: $(srcdir)/postgres.sgml $(ALMOSTALLSGML) - $(OSX) -D. -x lower -i include-xslt-index $< >postgres.xmltmp - $(PERL) -p -e 's/\[(aacute|acirc|aelig|agrave|amp|aring|atilde|auml|bull|copy|eacute|egrave|gt|iacute|lt|mdash|nbsp|ntilde|oacute|ocirc|oslash|ouml|pi|quot|scaron|uuml) *\]/\&\1;/gi;' \ - -e '$$_ .= qq{<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">\n} if $$. == 1;' \ - <postgres.xmltmp > $@ - rm postgres.xmltmp -# ' hello Emacs +postgres.xml: $(srcdir)/postgres.sgml $(ALLSGML) + $(OSX) $(SPFLAGS) $(SGMLINCLUDE) -x lower $< >[email protected] + $(call mangle-xml,book) + +define mangle-xml +$(PERL) -p -e 's/\[(aacute|acirc|aelig|agrave|amp|aring|atilde|auml|bull|copy|eacute|egrave|gt|iacute|lt|mdash|nbsp|ntilde|oacute|ocirc|oslash|ouml|pi|quot|scaron|uuml) *\]/\&\1;/gi;' \ + -e '$$_ .= qq{<!DOCTYPE $(1) PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">\n} if $$. == 1;' \ + <[email protected] > $@ +endef + + +## +## HTML +## ifeq ($(STYLE),website) XSLTPROC_HTML_FLAGS += --param website.stylesheet 1 endif -xslthtml: xslthtml-stamp +html: html-stamp -xslthtml-stamp: stylesheet.xsl postgres.xml +html-stamp: stylesheet.xsl postgres.xml $(XMLLINT) --noout --valid postgres.xml $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ cp $(srcdir)/stylesheet.css html/ @@ -270,24 +175,38 @@ htmlhelp: stylesheet-hh.xsl postgres.xml $(XMLLINT) --noout --valid postgres.xml $(XSLTPROC) $(XSLTPROCFLAGS) $^ -%-A4.fo.tmp: stylesheet-fo.xsl %.xml +# single-page HTML +postgres.html: stylesheet-html-nochunk.xsl postgres.xml + $(XMLLINT) --noout --valid postgres.xml + $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $^ + +# single-page text +postgres.txt: postgres.html + $(LYNX) -force_html -dump -nolist $< > $@ + + +## +## Print +## + +postgres.pdf: + $(error Invalid target; use postgres-A4.pdf or postgres-US.pdf as targets) + +%-A4.fo: stylesheet-fo.xsl %.xml $(XMLLINT) --noout --valid $*.xml $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type A4 -o $@ $^ -%-US.fo.tmp: stylesheet-fo.xsl %.xml +%-US.fo: stylesheet-fo.xsl %.xml $(XMLLINT) --noout --valid $*.xml $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $^ -FOP = fop +%.pdf: %.fo + $(FOP) -fo $< -pdf $@ -# reformat FO output so that locations of errors are easier to find -%.fo: %.fo.tmp - $(XMLLINT) --format --output $@ $^ -.SECONDARY: postgres-A4.fo postgres-US.fo - -%-fop.pdf: %.fo - $(FOP) -fo $< -pdf $@ +## +## EPUB +## epub: postgres.epub postgres.epub: postgres.xml @@ -318,7 +237,7 @@ MAKEINFO = makeinfo ## # Quick syntax check without style processing -check: postgres.sgml $(ALMOSTALLSGML) check-tabs +check: postgres.sgml $(ALLSGML) check-tabs $(NSGMLS) $(SPFLAGS) $(SGMLINCLUDE) -s $< @@ -326,11 +245,7 @@ check: postgres.sgml $(ALMOSTALLSGML) check-tabs ## Install ## -install: install-html - -ifneq ($(PORTNAME), sco) -install: install-man -endif +install: install-html install-man installdirs: $(MKDIR_P) '$(DESTDIR)$(htmldir)'/html $(addprefix '$(DESTDIR)$(mandir)'/man, 1 3 $(sqlmansectnum)) @@ -394,21 +309,23 @@ check-tabs: # This allows removing some files from the distribution tarballs while # keeping the dependencies satisfied. .SECONDARY: postgres.xml $(GENERATED_SGML) HTML.index -.SECONDARY: INSTALL.html -.SECONDARY: %-A4.tex-ps %-US.tex-ps %-A4.tex-pdf %-US.tex-pdf +.SECONDARY: INSTALL.html INSTALL.xml +.SECONDARY: postgres-A4.fo postgres-US.fo clean: # text --- these are shipped, but not in this directory rm -f INSTALL - rm -f INSTALL.html + rm -f INSTALL.html INSTALL.xml # single-page output rm -f postgres.html postgres.txt # print - rm -f *.rtf *.tex-ps *.tex-pdf *.dvi *.aux *.log *.ps *.pdf *.out *.fot -# index - rm -f HTML.index $(GENERATED_SGML) -# XSLT - rm -f postgres.xml postgres.xmltmp htmlhelp.hhp toc.hhc index.hhk *.fo *.fo.tmp + rm -f *.fo *.pdf +# generated SGML files + rm -f $(GENERATED_SGML) +# SGML->XML conversion + rm -f postgres.xml *.tmp +# HTML Help + rm -f htmlhelp.hhp toc.hhc index.hhk # EPUB rm -f postgres.epub # Texinfo diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml index 6906e2a1ae..93b5652ae7 100644 --- a/doc/src/sgml/acronyms.sgml +++ b/doc/src/sgml/acronyms.sgml @@ -318,7 +318,7 @@ <listitem> <para> <ulink - url="http://git.postgresql.org/gitweb?p=postgresql.git;a=blob;f=src/backend/access/heap/README.HOT;hb=HEAD">Heap-Only + url="https://git.postgresql.org/gitweb?p=postgresql.git;a=blob;f=src/backend/access/heap/README.HOT;hb=HEAD">Heap-Only Tuples</ulink> </para> </listitem> @@ -399,6 +399,16 @@ </varlistentry> <varlistentry> + <term><acronym>LSN</acronym></term> + <listitem> + <para> + Log Sequence Number, see <link linkend="datatype-pg-lsn"><type>pg_lsn</></link> + and <link linkend="wal-internals">WAL Internals</link>. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><acronym>MSVC</acronym></term> <listitem> <para> diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml index d66268e0ab..77b890d13f 100644 --- a/doc/src/sgml/advanced.sgml +++ b/doc/src/sgml/advanced.sgml @@ -342,8 +342,8 @@ COMMIT; A <firstterm>window function</> performs a calculation across a set of table rows that are somehow related to the current row. This is comparable to the type of calculation that can be done with an aggregate function. - But unlike regular aggregate functions, use of a window function does not - cause rows to become grouped into a single output row — the + However, window functions do not cause rows to become grouped into a single + output row like non-window aggregate calls would. Instead, the rows retain their separate identities. Behind the scenes, the window function is able to access more than just the current row of the query result. @@ -377,20 +377,19 @@ SELECT depname, empno, salary, avg(salary) OVER (PARTITION BY depname) FROM emps <structname>empsalary</>, and there is one output row for each row in the table. The fourth column represents an average taken across all the table rows that have the same <structfield>depname</> value as the current row. - (This actually is the same function as the regular <function>avg</> - aggregate function, but the <literal>OVER</> clause causes it to be - treated as a window function and computed across an appropriate set of - rows.) + (This actually is the same function as the non-window <function>avg</> + aggregate, but the <literal>OVER</> clause causes it to be + treated as a window function and computed across the window frame.) </para> <para> A window function call always contains an <literal>OVER</> clause directly following the window function's name and argument(s). This is what - syntactically distinguishes it from a regular function or aggregate - function. The <literal>OVER</> clause determines exactly how the + syntactically distinguishes it from a normal function or non-window + aggregate. The <literal>OVER</> clause determines exactly how the rows of the query are split up for processing by the window function. - The <literal>PARTITION BY</> list within <literal>OVER</> specifies - dividing the rows into groups, or partitions, that share the same + The <literal>PARTITION BY</> clause within <literal>OVER</> + divides the rows into groups, or partitions, that share the same values of the <literal>PARTITION BY</> expression(s). For each row, the window function is computed across the rows that fall into the same partition as the current row. @@ -425,8 +424,8 @@ FROM empsalary; </screen> As shown here, the <function>rank</> function produces a numerical rank - within the current row's partition for each distinct <literal>ORDER BY</> - value, in the order defined by the <literal>ORDER BY</> clause. + for each distinct <literal>ORDER BY</> value in the current row's + partition, using the order defined by the <literal>ORDER BY</> clause. <function>rank</> needs no explicit parameter, because its behavior is entirely determined by the <literal>OVER</> clause. </para> @@ -438,20 +437,20 @@ FROM empsalary; if any. For example, a row removed because it does not meet the <literal>WHERE</> condition is not seen by any window function. A query can contain multiple window functions that slice up the data - in different ways by means of different <literal>OVER</> clauses, but + in different ways using different <literal>OVER</> clauses, but they all act on the same collection of rows defined by this virtual table. </para> <para> We already saw that <literal>ORDER BY</> can be omitted if the ordering of rows is not important. It is also possible to omit <literal>PARTITION - BY</>, in which case there is just one partition containing all the rows. + BY</>, in which case there is a single partition containing all rows. </para> <para> There is another important concept associated with window functions: for each row, there is a set of rows within its partition called its - <firstterm>window frame</>. Many (but not all) window functions act only + <firstterm>window frame</>. Some window functions act only on the rows of the window frame, rather than of the whole partition. By default, if <literal>ORDER BY</> is supplied then the frame consists of all rows from the start of the partition up through the current row, plus @@ -529,7 +528,7 @@ SELECT salary, sum(salary) OVER (ORDER BY salary) FROM empsalary; elsewhere, such as in <literal>GROUP BY</>, <literal>HAVING</> and <literal>WHERE</literal> clauses. This is because they logically execute after the processing of those clauses. Also, window functions - execute after regular aggregate functions. This means it is valid to + execute after non-window aggregate functions. This means it is valid to include an aggregate function call in the arguments of a window function, but not vice versa. </para> @@ -726,7 +725,7 @@ SELECT name, altitude <para> If you feel you need more introductory material, please visit the PostgreSQL - <ulink url="http://www.postgresql.org">web site</ulink> + <ulink url="https://www.postgresql.org">web site</ulink> for links to more resources. </para> </sect1> diff --git a/doc/src/sgml/amcheck.sgml b/doc/src/sgml/amcheck.sgml new file mode 100644 index 0000000000..893a5b41d9 --- /dev/null +++ b/doc/src/sgml/amcheck.sgml @@ -0,0 +1,273 @@ +<!-- doc/src/sgml/amcheck.sgml --> + +<sect1 id="amcheck" xreflabel="amcheck"> + <title>amcheck</title> + + <indexterm zone="amcheck"> + <primary>amcheck</primary> + </indexterm> + + <para> + The <filename>amcheck</> module provides functions that allow you to + verify the logical consistency of the structure of indexes. If the + structure appears to be valid, no error is raised. + </para> + + <para> + The functions verify various <emphasis>invariants</> in the + structure of the representation of particular indexes. The + correctness of the access method functions behind index scans and + other important operations relies on these invariants always + holding. For example, certain functions verify, among other things, + that all B-Tree pages have items in <quote>logical</> order (e.g., + for B-Tree indexes on <type>text</>, index tuples should be in + collated lexical order). If that particular invariant somehow fails + to hold, we can expect binary searches on the affected page to + incorrectly guide index scans, resulting in wrong answers to SQL + queries. + </para> + <para> + Verification is performed using the same procedures as those used by + index scans themselves, which may be user-defined operator class + code. For example, B-Tree index verification relies on comparisons + made with one or more B-Tree support function 1 routines. See <xref + linkend="xindex-support"> for details of operator class support + functions. + </para> + <para> + <filename>amcheck</> functions may be used only by superusers. + </para> + + <sect2> + <title>Functions</title> + + <variablelist> + <varlistentry> + <term> + <function>bt_index_check(index regclass) returns void</function> + <indexterm> + <primary>bt_index_check</primary> + </indexterm> + </term> + + <listitem> + <para> + <function>bt_index_check</function> tests that its target, a + B-Tree index, respects a variety of invariants. Example usage: +<screen> +test=# SELECT bt_index_check(c.oid), c.relname, c.relpages +FROM pg_index i +JOIN pg_opclass op ON i.indclass[0] = op.oid +JOIN pg_am am ON op.opcmethod = am.oid +JOIN pg_class c ON i.indexrelid = c.oid +JOIN pg_namespace n ON c.relnamespace = n.oid +WHERE am.amname = 'btree' AND n.nspname = 'pg_catalog' +-- Don't check temp tables, which may be from another session: +AND c.relpersistence != 't' +-- Function may throw an error when this is omitted: +AND i.indisready AND i.indisvalid +ORDER BY c.relpages DESC LIMIT 10; + bt_index_check | relname | relpages +----------------+---------------------------------+---------- + | pg_depend_reference_index | 43 + | pg_depend_depender_index | 40 + | pg_proc_proname_args_nsp_index | 31 + | pg_description_o_c_o_index | 21 + | pg_attribute_relid_attnam_index | 14 + | pg_proc_oid_index | 10 + | pg_attribute_relid_attnum_index | 9 + | pg_amproc_fam_proc_index | 5 + | pg_amop_opr_fam_index | 5 + | pg_amop_fam_strat_index | 5 +(10 rows) +</screen> + This example shows a session that performs verification of every + catalog index in the database <quote>test</>. Details of just + the 10 largest indexes verified are displayed. Since no error + is raised, all indexes tested appear to be logically consistent. + Naturally, this query could easily be changed to call + <function>bt_index_check</function> for every index in the + database where verification is supported. + </para> + <para> + <function>bt_index_check</function> acquires an <literal>AccessShareLock</> + on the target index and the heap relation it belongs to. This lock mode + is the same lock mode acquired on relations by simple + <literal>SELECT</> statements. + <function>bt_index_check</function> does not verify invariants + that span child/parent relationships, nor does it verify that + the target index is consistent with its heap relation. When a + routine, lightweight test for corruption is required in a live + production environment, using + <function>bt_index_check</function> often provides the best + trade-off between thoroughness of verification and limiting the + impact on application performance and availability. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <function>bt_index_parent_check(index regclass) returns void</function> + <indexterm> + <primary>bt_index_parent_check</primary> + </indexterm> + </term> + + <listitem> + <para> + <function>bt_index_parent_check</function> tests that its + target, a B-Tree index, respects a variety of invariants. The + checks performed by <function>bt_index_parent_check</function> + are a superset of the checks performed by + <function>bt_index_check</function>. + <function>bt_index_parent_check</function> can be thought of as + a more thorough variant of <function>bt_index_check</function>: + unlike <function>bt_index_check</function>, + <function>bt_index_parent_check</function> also checks + invariants that span parent/child relationships. However, it + does not verify that the target index is consistent with its + heap relation. <function>bt_index_parent_check</function> + follows the general convention of raising an error if it finds a + logical inconsistency or other problem. + </para> + <para> + A <literal>ShareLock</> is required on the target index by + <function>bt_index_parent_check</function> (a + <literal>ShareLock</> is also acquired on the heap relation). + These locks prevent concurrent data modification from + <command>INSERT</>, <command>UPDATE</>, and <command>DELETE</> + commands. The locks also prevent the underlying relation from + being concurrently processed by <command>VACUUM</>, as well as + all other utility commands. Note that the function holds locks + only while running, not for the entire transaction. + </para> + <para> + <function>bt_index_parent_check</function>'s additional + verification is more likely to detect various pathological + cases. These cases may involve an incorrectly implemented + B-Tree operator class used by the index that is checked, or, + hypothetically, undiscovered bugs in the underlying B-Tree index + access method code. Note that + <function>bt_index_parent_check</function> cannot be used when + Hot Standby mode is enabled (i.e., on read-only physical + replicas), unlike <function>bt_index_check</function>. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2> + <title>Using <filename>amcheck</> effectively</title> + + <para> + <filename>amcheck</> can be effective at detecting various types of + failure modes that <link + linkend="app-initdb-data-checksums"><application>data page + checksums</></link> will always fail to catch. These include: + + <itemizedlist> + <listitem> + <para> + Structural inconsistencies caused by incorrect operator class + implementations. + </para> + <para> + This includes issues caused by the comparison rules of operating + system collations changing. Comparisons of datums of a collatable + type like <type>text</> must be immutable (just as all + comparisons used for B-Tree index scans must be immutable), which + implies that operating system collation rules must never change. + Though rare, updates to operating system collation rules can + cause these issues. More commonly, an inconsistency in the + collation order between a master server and a standby server is + implicated, possibly because the <emphasis>major</> operating + system version in use is inconsistent. Such inconsistencies will + generally only arise on standby servers, and so can generally + only be detected on standby servers. + </para> + <para> + If a problem like this arises, it may not affect each individual + index that is ordered using an affected collation, simply because + <emphasis>indexed</> values might happen to have the same + absolute ordering regardless of the behavioral inconsistency. See + <xref linkend="locale"> and <xref linkend="collation"> for + further details about how <productname>PostgreSQL</> uses + operating system locales and collations. + </para> + </listitem> + <listitem> + <para> + Corruption caused by hypothetical undiscovered bugs in the + underlying <productname>PostgreSQL</> access method code or sort + code. + </para> + <para> + Automatic verification of the structural integrity of indexes + plays a role in the general testing of new or proposed + <productname>PostgreSQL</> features that could plausibly allow a + logical inconsistency to be introduced. One obvious testing + strategy is to call <filename>amcheck</> functions continuously + when running the standard regression tests. See <xref + linkend="regress-run"> for details on running the tests. + </para> + </listitem> + <listitem> + <para> + Filesystem or storage subsystem faults where checksums happen to + simply not be enabled. + </para> + <para> + Note that <filename>amcheck</> examines a page as represented in some + shared memory buffer at the time of verification if there is only a + shared buffer hit when accessing the block. Consequently, + <filename>amcheck</> does not necessarily examine data read from the + filesystem at the time of verification. Note that when checksums are + enabled, <filename>amcheck</> may raise an error due to a checksum + failure when a corrupt block is read into a buffer. + </para> + </listitem> + <listitem> + <para> + Corruption caused by faulty RAM, and the broader memory subsystem + and operating system. + </para> + <para> + <productname>PostgreSQL</> does not protect against correctable + memory errors and it is assumed you will operate using RAM that + uses industry standard Error Correcting Codes (ECC) or better + protection. However, ECC memory is typically only immune to + single-bit errors, and should not be assumed to provide + <emphasis>absolute</emphasis> protection against failures that + result in memory corruption. + </para> + </listitem> + </itemizedlist> + In general, <filename>amcheck</> can only prove the presence of + corruption; it cannot prove its absence. + </para> + + </sect2> + <sect2> + <title>Repairing corruption</title> + <para> + No error concerning corruption raised by <filename>amcheck</> should + ever be a false positive. In practice, <filename>amcheck</> is more + likely to find software bugs than problems with hardware. + <filename>amcheck</> raises errors in the event of conditions that, + by definition, should never happen, and so careful analysis of + <filename>amcheck</> errors is often required. + </para> + <para> + There is no general method of repairing problems that + <filename>amcheck</> detects. An explanation for the root cause of + an invariant violation should be sought. <xref + linkend="pageinspect"> may play a useful role in diagnosing + corruption that <filename>amcheck</> detects. A <command>REINDEX</> + may not be effective in repairing corruption. + </para> + + </sect2> + +</sect1> diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml index cfe8c86750..ca38573471 100644 --- a/doc/src/sgml/backup.sgml +++ b/doc/src/sgml/backup.sgml @@ -399,10 +399,10 @@ tar -cf backup.tar /usr/local/pgsql/data directories. This will <emphasis>not</> work because the information contained in these files is not usable without the commit log files, - <filename>pg_clog/*</filename>, which contain the commit status of + <filename>pg_xact/*</filename>, which contain the commit status of all transactions. A table file is only usable with this information. Of course it is also impossible to restore only a - table and the associated <filename>pg_clog</filename> data + table and the associated <filename>pg_xact</filename> data because that would render all other tables in the database cluster useless. So file system backups only work for complete backup and restoration of an entire database cluster. @@ -489,7 +489,7 @@ tar -cf backup.tar /usr/local/pgsql/data <para> At all times, <productname>PostgreSQL</> maintains a - <firstterm>write ahead log</> (WAL) in the <filename>pg_xlog/</> + <firstterm>write ahead log</> (WAL) in the <filename>pg_wal/</> subdirectory of the cluster's data directory. The log records every change made to the database's data files. This log exists primarily for crash-safety purposes: if the system crashes, the @@ -633,7 +633,7 @@ archive_command = 'copy "%p" "C:\\server\\archivedir\\%f"' # Windows <literal>%p</> and <literal>%f</> parameters have been replaced, the actual command executed might look like this: <programlisting> -test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_xlog/00000001000000A900000065 /mnt/server/archivedir/00000001000000A900000065 +test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/00000001000000A900000065 /mnt/server/archivedir/00000001000000A900000065 </programlisting> A similar command will be generated for each new file to be archived. </para> @@ -685,9 +685,9 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_xlog/ fills, nothing further can be archived until the tape is swapped. You should ensure that any error condition or request to a human operator is reported appropriately so that the situation can be - resolved reasonably quickly. The <filename>pg_xlog/</> directory will + resolved reasonably quickly. The <filename>pg_wal/</> directory will continue to fill with WAL segment files until the situation is resolved. - (If the file system containing <filename>pg_xlog/</> fills up, + (If the file system containing <filename>pg_wal/</> fills up, <productname>PostgreSQL</> will do a PANIC shutdown. No committed transactions will be lost, but the database will remain offline until you free some space.) @@ -699,7 +699,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_xlog/ operation continues even if the archiving process falls a little behind. If archiving falls significantly behind, this will increase the amount of data that would be lost in the event of a disaster. It will also mean that - the <filename>pg_xlog/</> directory will contain large numbers of + the <filename>pg_wal/</> directory will contain large numbers of not-yet-archived segment files, which could eventually exceed available disk space. You are advised to monitor the archiving process to ensure that it is working as you intend. @@ -743,7 +743,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_xlog/ <para> Also, you can force a segment switch manually with - <function>pg_switch_xlog</> if you want to ensure that a + <function>pg_switch_wal</> if you want to ensure that a just-finished transaction is archived as soon as possible. Other utility functions related to WAL management are listed in <xref linkend="functions-admin-backup-table">. @@ -760,7 +760,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_xlog/ configuration file reload. If you wish to temporarily stop archiving, one way to do it is to set <varname>archive_command</> to the empty string (<literal>''</>). - This will cause WAL files to accumulate in <filename>pg_xlog/</> until a + This will cause WAL files to accumulate in <filename>pg_wal/</> until a working <varname>archive_command</> is re-established. </para> </sect2> @@ -879,7 +879,8 @@ SELECT pg_start_backup('label', false, false); <xref linkend="guc-checkpoint-completion-target">). This is usually what you want, because it minimizes the impact on query processing. If you want to start the backup as soon as - possible, change the second parameter to <literal>true</>. + possible, change the second parameter to <literal>true</>, which will + issue an immediate checkpoint using as much I/O as available. </para> <para> @@ -894,7 +895,7 @@ SELECT pg_start_backup('label', false, false); <application>pg_dump</application> or <application>pg_dumpall</application>). It is neither necessary nor desirable to stop normal operation of the database - while you do this. See section + while you do this. See <xref linkend="backup-lowlevel-base-backup-data"> for things to consider during this backup. </para> @@ -903,7 +904,7 @@ SELECT pg_start_backup('label', false, false); <para> In the same connection as before, issue the command: <programlisting> -SELECT * FROM pg_stop_backup(false); +SELECT * FROM pg_stop_backup(false, true); </programlisting> This terminates the backup mode and performs an automatic switch to the next WAL segment. The reason for the switch is to arrange for @@ -940,6 +941,17 @@ SELECT * FROM pg_stop_backup(false); <function>pg_stop_backup</> terminates because of this your backup may not be valid. </para> + <para> + If the backup process monitors and ensures that all WAL segment files + required for the backup are successfully archived then the second + parameter (which defaults to true) can be set to false to have + <function>pg_stop_backup</> return as soon as the stop backup record is + written to the WAL. By default, <function>pg_stop_backup</> will wait + until all WAL has been archived, which can take some time. This option + must be used with caution: if WAL archiving is not monitored correctly + then the backup might not include all of the WAL files and will + therefore be incomplete and not able to be restored. + </para> </listitem> </orderedlist> </para> @@ -1004,7 +1016,7 @@ SELECT pg_start_backup('label', true); <application>pg_dump</application> or <application>pg_dumpall</application>). It is neither necessary nor desirable to stop normal operation of the database - while you do this. See section + while you do this. See <xref linkend="backup-lowlevel-base-backup-data"> for things to consider during this backup. </para> @@ -1079,10 +1091,10 @@ SELECT pg_stop_backup(); <para> You should, however, omit from the backup the files within the - cluster's <filename>pg_xlog/</> subdirectory. This + cluster's <filename>pg_wal/</> subdirectory. This slight adjustment is worthwhile because it reduces the risk of mistakes when restoring. This is easy to arrange if - <filename>pg_xlog/</> is a symbolic link pointing to someplace outside + <filename>pg_wal/</> is a symbolic link pointing to someplace outside the cluster directory, which is a common setup anyway for performance reasons. You might also want to exclude <filename>postmaster.pid</> and <filename>postmaster.opts</>, which record information @@ -1107,6 +1119,22 @@ SELECT pg_stop_backup(); </para> <para> + The contents of the directories <filename>pg_dynshmem/</>, + <filename>pg_notify/</>, <filename>pg_serial/</>, + <filename>pg_snapshots/</>, <filename>pg_stat_tmp/</>, + and <filename>pg_subtrans/</> (but not the directories themselves) can be + omitted from the backup as they will be initialized on postmaster startup. + If <xref linkend="guc-stats-temp-directory"> is set and is under the data + directory then the contents of that directory can also be omitted. + </para> + + <para> + Any file or directory beginning with <filename>pgsql_tmp</filename> can be + omitted from the backup. These files are removed on postmaster start and + the directories will be recreated as needed. + </para> + + <para> The backup label file includes the label string you gave to <function>pg_start_backup</>, as well as the time at which <function>pg_start_backup</> was run, and @@ -1150,7 +1178,7 @@ SELECT pg_stop_backup(); location in case you need them later. Note that this precaution will require that you have enough free space on your system to hold two copies of your existing database. If you do not have enough space, - you should at least save the contents of the cluster's <filename>pg_xlog</> + you should at least save the contents of the cluster's <filename>pg_wal</> subdirectory, as it might contain logs which were not archived before the system went down. </para> @@ -1173,9 +1201,9 @@ SELECT pg_stop_backup(); </listitem> <listitem> <para> - Remove any files present in <filename>pg_xlog/</>; these came from the + Remove any files present in <filename>pg_wal/</>; these came from the file system backup and are therefore probably obsolete rather than current. - If you didn't archive <filename>pg_xlog/</> at all, then recreate + If you didn't archive <filename>pg_wal/</> at all, then recreate it with proper permissions, being careful to ensure that you re-establish it as a symbolic link if you had it set up that way before. @@ -1184,7 +1212,7 @@ SELECT pg_stop_backup(); <listitem> <para> If you have unarchived WAL segment files that you saved in step 2, - copy them into <filename>pg_xlog/</>. (It is best to copy them, + copy them into <filename>pg_wal/</>. (It is best to copy them, not move them, so you still have the unmodified files if a problem occurs and you have to start over.) </para> @@ -1266,9 +1294,9 @@ restore_command = 'cp /mnt/server/archivedir/%f %p' <para> WAL segments that cannot be found in the archive will be sought in - <filename>pg_xlog/</>; this allows use of recent un-archived segments. + <filename>pg_wal/</>; this allows use of recent un-archived segments. However, segments that are available from the archive will be used in - preference to files in <filename>pg_xlog/</>. + preference to files in <filename>pg_wal/</>. </para> <para> @@ -1413,7 +1441,7 @@ restore_command = 'cp /mnt/server/archivedir/%f %p' As with base backups, the easiest way to produce a standalone hot backup is to use the <xref linkend="app-pgbasebackup"> tool. If you include the <literal>-X</> parameter when calling - it, all the transaction log required to use the backup will be + it, all the write-ahead log required to use the backup will be included in the backup automatically, and no special action is required to restore the backup. </para> @@ -1421,7 +1449,8 @@ restore_command = 'cp /mnt/server/archivedir/%f %p' <para> If more flexibility in copying the backup files is needed, a lower level process can be used for standalone hot backups as well. - To prepare for low level standalone hot backups, set <varname>wal_level</> to + To prepare for low level standalone hot backups, make sure + <varname>wal_level</> is set to <literal>replica</> or higher, <varname>archive_mode</> to <literal>on</>, and set up an <varname>archive_command</> that performs archiving only when a <emphasis>switch file</> exists. For example: @@ -1537,19 +1566,6 @@ archive_command = 'local_backup_script.sh "%p" "%f"' <itemizedlist> <listitem> <para> - Operations on hash indexes are not presently WAL-logged, so - replay will not update these indexes. This will mean that any new inserts - will be ignored by the index, updated rows will apparently disappear and - deleted rows will still retain pointers. In other words, if you modify a - table with a hash index on it then you will get incorrect query results - on a standby server. When recovery completes it is recommended that you - manually <xref linkend="sql-reindex"> - each such index after completing a recovery operation. - </para> - </listitem> - - <listitem> - <para> If a <xref linkend="sql-createdatabase"> command is executed while a base backup is being taken, and then the template database that the <command>CREATE DATABASE</> copied diff --git a/doc/src/sgml/bgworker.sgml b/doc/src/sgml/bgworker.sgml index 07f9f1081c..b422323081 100644 --- a/doc/src/sgml/bgworker.sgml +++ b/doc/src/sgml/bgworker.sgml @@ -54,9 +54,8 @@ typedef struct BackgroundWorker int bgw_flags; BgWorkerStartTime bgw_start_time; int bgw_restart_time; /* in seconds, or BGW_NEVER_RESTART */ - bgworker_main_type bgw_main; - char bgw_library_name[BGW_MAXLEN]; /* only if bgw_main is NULL */ - char bgw_function_name[BGW_MAXLEN]; /* only if bgw_main is NULL */ + char bgw_library_name[BGW_MAXLEN]; + char bgw_function_name[BGW_MAXLEN]; Datum bgw_main_arg; char bgw_extra[BGW_EXTRALEN]; int bgw_notify_pid; @@ -131,26 +130,12 @@ typedef struct BackgroundWorker </para> <para> - <structfield>bgw_main</structfield> is a pointer to the function to run when - the process is started. This field can only safely be used to launch - functions within the core server, because shared libraries may be loaded - at different starting addresses in different backend processes. This will - happen on all platforms when the library is loaded using any mechanism - other than <xref linkend="guc-shared-preload-libraries">. Even when that - mechanism is used, address space layout variations will still occur on - Windows, and when <literal>EXEC_BACKEND</> is used. Therefore, most users - of this API should set this field to NULL. If it is non-NULL, it takes - precedence over <structfield>bgw_library_name</> and - <structfield>bgw_function_name</>. - </para> - - <para> <structfield>bgw_library_name</structfield> is the name of a library in which the initial entry point for the background worker should be sought. The named library will be dynamically loaded by the worker process and <structfield>bgw_function_name</structfield> will be used to identify the - function to be called. If loading a function from the core code, - <structfield>bgw_main</> should be set instead. + function to be called. If loading a function from the core code, this must + be set to "postgres". </para> <para> @@ -161,13 +146,10 @@ typedef struct BackgroundWorker <para> <structfield>bgw_main_arg</structfield> is the <type>Datum</> argument - to the background worker main function. Regardless of whether that - function is specified via <structfield>bgw_main</> or via the combination - of <function>bgw_library_name</> and <function>bgw_function_name</>, - this main function should take a single argument of type <type>Datum</> - and return <type>void</>. <structfield>bgw_main_arg</structfield> will be - passed as the argument. In addition, the global variable - <literal>MyBgworkerEntry</literal> + to the background worker main function. This main function should take a + single argument of type <type>Datum</> and return <type>void</>. + <structfield>bgw_main_arg</structfield> will be passed as the argument. + In addition, the global variable <literal>MyBgworkerEntry</literal> points to a copy of the <structname>BackgroundWorker</structname> structure passed at registration time; the worker may find it helpful to examine this structure. @@ -215,7 +197,7 @@ typedef struct BackgroundWorker <para> Signals are initially blocked when control reaches the - <structfield>bgw_main</> function, and must be unblocked by it; this is to + background worker's main function, and must be unblocked by it; this is to allow the process to customize its signal handlers, if necessary. Signals can be unblocked in the new process by calling <function>BackgroundWorkerUnblockSignals</> and blocked by calling diff --git a/doc/src/sgml/biblio.sgml b/doc/src/sgml/biblio.sgml index 7968372ae5..6546dd09ef 100644 --- a/doc/src/sgml/biblio.sgml +++ b/doc/src/sgml/biblio.sgml @@ -12,17 +12,14 @@ Some white papers and technical reports from the original <productname>POSTGRES</productname> development team are available at the University of California, Berkeley, Computer Science - Department <ulink url="http://db.cs.berkeley.edu/papers/"> - web site</ulink>. + Department <ulink url="http://db.cs.berkeley.edu/papers/">web site</ulink>. </para> <bibliodiv> <title><acronym>SQL</acronym> Reference Books</title> - <para>Reference texts for <acronym>SQL</acronym> features.</para> <biblioentry id="BOWMAN01"> <title>The Practical <acronym>SQL</acronym> Handbook</title> - <titleabbrev>Bowman et al, 2001</titleabbrev> <subtitle>Using SQL Variants</subtitle> <edition>Fourth Edition</edition> <authorgroup> @@ -40,18 +37,14 @@ </author> </authorgroup> <isbn>0-201-70309-2</isbn> - <pubdate>2001</pubdate> <publisher> <publishername>Addison-Wesley Professional</publishername> </publisher> - <copyright> - <year>2001</year> - </copyright> + <pubdate>2001</pubdate> </biblioentry> <biblioentry id="DATE97"> <title>A Guide to the <acronym>SQL</acronym> Standard</title> - <titleabbrev>Date and Darwen, 1997</titleabbrev> <subtitle>A user's guide to the standard database language <acronym>SQL</acronym></subtitle> <edition>Fourth Edition</edition> <authorgroup> @@ -65,19 +58,14 @@ </author> </authorgroup> <isbn>0-201-96426-0</isbn> - <pubdate>1997</pubdate> <publisher> <publishername>Addison-Wesley</publishername> </publisher> - <copyright> - <year>1997</year> - <holder>Addison-Wesley Longman, Inc.</holder> - </copyright> + <pubdate>1997</pubdate> </biblioentry> <biblioentry id="DATE04"> <title>An Introduction to Database Systems</title> - <titleabbrev>Date, 2004</titleabbrev> <edition>Eighth Edition</edition> <authorgroup> <author> @@ -86,14 +74,10 @@ </author> </authorgroup> <isbn>0-321-19784-4</isbn> - <pubdate>2003</pubdate> <publisher> <publishername>Addison-Wesley</publishername> </publisher> - <copyright> - <year>2004</year> - <holder>Pearson Education, Inc.</holder> - </copyright> + <pubdate>2003</pubdate> </biblioentry> <biblioentry id="ELMA04"> @@ -110,18 +94,14 @@ </author> </authorgroup> <isbn>0-321-12226-7</isbn> - <pubdate>2003</pubdate> <publisher> <publishername>Addison-Wesley</publishername> </publisher> - <copyright> - <year>2004</year> - </copyright> + <pubdate>2003</pubdate> </biblioentry> <biblioentry id="MELT93"> <title>Understanding the New <acronym>SQL</acronym></title> - <titleabbrev>Melton and Simon, 1993</titleabbrev> <subtitle>A complete guide</subtitle> <authorgroup> <author> @@ -134,20 +114,15 @@ </author> </authorgroup> <isbn>1-55860-245-3</isbn> - <pubdate>1993</pubdate> <publisher> <publishername>Morgan Kaufmann</publishername> </publisher> - <copyright> - <year>1993</year> - <holder>Morgan Kaufmann Publishers, Inc.</holder> - </copyright> + <pubdate>1993</pubdate> </biblioentry> <biblioentry id="ULL88"> <title>Principles of Database and Knowledge</title> <subtitle>Base Systems</subtitle> - <titleabbrev>Ullman, 1988</titleabbrev> <authorgroup> <author> <firstname>Jeffrey D.</firstname> @@ -165,11 +140,9 @@ <bibliodiv> <title>PostgreSQL-specific Documentation</title> - <para>This section is for related documentation.</para> <biblioentry id="SIM98"> <title>Enhancement of the ANSI SQL Implementation of PostgreSQL</title> - <titleabbrev>Simkovics, 1998</titleabbrev> <authorgroup> <author> <firstname>Stefan</firstname> @@ -205,16 +178,15 @@ [email protected] </para> </abstract> - <pubdate>November 29, 1998</pubdate> <publisher> <publishername>Department of Information Systems, Vienna University of Technology</publishername> <address>Vienna, Austria</address> </publisher> + <pubdate>November 29, 1998</pubdate> </biblioentry> <biblioentry id="YU95"> <title>The <productname>Postgres95</productname> User Manual</title> - <titleabbrev>Yu and Chen, 1995</titleabbrev> <authorgroup> <author> <firstname>A.</firstname> @@ -225,24 +197,17 @@ [email protected] <surname>Chen</surname> </author> </authorgroup> - <authorgroup> - <collab> - <collabname>The POSTGRES Group</collabname> - </collab> - </authorgroup> - - <pubdate>Sept. 5, 1995</pubdate> <publisher> <publishername>University of California</publishername> <address>Berkeley, California</address> </publisher> + <pubdate>Sept. 5, 1995</pubdate> </biblioentry> <biblioentry id="FONG"> - <title> - <ulink url="http://db.cs.berkeley.edu/papers/UCB-MS-zfong.pdf"> - The design and implementation of the <productname>POSTGRES</productname> query optimizer - </ulink></title> + <title><ulink url="http://db.cs.berkeley.edu/papers/UCB-MS-zfong.pdf">The + design and implementation of the <productname>POSTGRES</productname> query + optimizer</ulink></title> <author> <firstname>Zelaine</firstname> <surname>Fong</surname> @@ -256,29 +221,26 @@ [email protected] <bibliodiv> <title>Proceedings and Articles</title> - <para>This section is for articles and newsletters.</para> <biblioentry id="OLSON93"> <title>Partial indexing in POSTGRES: research project</title> - <titleabbrev>Olson, 1993</titleabbrev> <authorgroup> <author> <firstname>Nels</firstname> <surname>Olson</surname> </author> </authorgroup> - <pubdate>1993</pubdate> <pubsnumber>UCB Engin T7.49.1993 O676</pubsnumber> <publisher> <publishername>University of California</publishername> <address>Berkeley, California</address> </publisher> + <pubdate>1993</pubdate> </biblioentry> <biblioentry id="ONG90"> <biblioset relation="article"> <title>A Unified Framework for Version Modeling Using Production Rules in a Database System</title> - <titleabbrev>Ong and Goh, 1990</titleabbrev> <authorgroup> <author> <firstname>L.</firstname> @@ -292,20 +254,18 @@ [email protected] </biblioset> <biblioset relation="journal"> <title>ERL Technical Memorandum M90/33</title> - <pubdate>April, 1990</pubdate> <publisher> <publishername>University of California</publishername> - <address>Berkely, California</address> + <address>Berkeley, California</address> </publisher> + <pubdate>April, 1990</pubdate> </biblioset> </biblioentry> <biblioentry id="ROWE87"> <biblioset relation="article"> - <title><ulink url="http://db.cs.berkeley.edu/papers/ERL-M87-13.pdf"> - The <productname>POSTGRES</productname> data model - </ulink></title> - <titleabbrev>Rowe and Stonebraker, 1987</titleabbrev> + <title><ulink url="http://db.cs.berkeley.edu/papers/ERL-M87-13.pdf">The <productname>POSTGRES</productname> + data model</ulink></title> <authorgroup> <author> <firstname>L.</firstname> @@ -326,14 +286,8 @@ [email protected] <biblioentry id="SESHADRI95"> <biblioset relation="article"> - <title>Generalized Partial Indexes - <ulink url="http://citeseer.ist.psu.edu/seshadri95generalized.html">(cached version) -<!-- - Original URL: http://citeseer.ist.psu.edu/seshadri95generalized.html ---> - </ulink> - </title> - <titleabbrev>Seshardri, 1995</titleabbrev> + <title><ulink url="http://citeseer.ist.psu.edu/seshadri95generalized.html">Generalized + Partial Indexes</ulink></title> <authorgroup> <author> <firstname>P.</firstname> @@ -350,21 +304,19 @@ [email protected] <confdates>6-10 March 1995</confdates> <address>Taipeh, Taiwan</address> </confgroup> - <pubdate>1995</pubdate> <pubsnumber>Cat. No.95CH35724</pubsnumber> <publisher> <publishername>IEEE Computer Society Press</publishername> <address>Los Alamitos, California</address> </publisher> + <pubdate>1995</pubdate> <pagenums>420-7</pagenums> </biblioentry> <biblioentry id="STON86"> <biblioset relation="article"> - <title><ulink url="http://db.cs.berkeley.edu/papers/ERL-M85-95.pdf"> - The design of <productname>POSTGRES</productname> - </ulink></title> - <titleabbrev>Stonebraker and Rowe, 1986</titleabbrev> + <title><ulink url="http://db.cs.berkeley.edu/papers/ERL-M85-95.pdf">The + design of <productname>POSTGRES</productname></ulink></title> <authorgroup> <author> <firstname>M.</firstname> @@ -386,7 +338,6 @@ [email protected] <biblioentry id="STON87a"> <biblioset relation="article"> <title>The design of the <productname>POSTGRES</productname> rules system</title> - <titleabbrev>Stonebraker, Hanson, Hong, 1987</titleabbrev> <authorgroup> <author> <firstname>M.</firstname> @@ -411,10 +362,9 @@ [email protected] <biblioentry id="STON87b"> <biblioset relation="article"> - <title><ulink url="http://db.cs.berkeley.edu/papers/ERL-M87-06.pdf"> - The design of the <productname>POSTGRES</productname> storage system - </ulink></title> - <titleabbrev>Stonebraker, 1987</titleabbrev> + <title><ulink url="http://db.cs.berkeley.edu/papers/ERL-M87-06.pdf">The + design of the <productname>POSTGRES</productname> storage + system</ulink></title> <authorgroup> <author> <firstname>M.</firstname> @@ -431,10 +381,9 @@ [email protected] <biblioentry id="STON89"> <biblioset relation="article"> - <title><ulink url="http://db.cs.berkeley.edu/papers/ERL-M89-82.pdf"> - A commentary on the <productname>POSTGRES</productname> rules system - </ulink></title> - <titleabbrev>Stonebraker et al, 1989</titleabbrev> + <title><ulink url="http://db.cs.berkeley.edu/papers/ERL-M89-82.pdf">A + commentary on the <productname>POSTGRES</productname> rules + system</ulink></title> <authorgroup> <author> <firstname>M.</firstname> @@ -458,10 +407,8 @@ [email protected] <biblioentry id="STON89b"> <biblioset relation="article"> - <title><ulink url="http://db.cs.berkeley.edu/papers/ERL-M89-17.pdf"> - The case for partial indexes - </ulink></title> - <titleabbrev>Stonebraker, M, 1989b</titleabbrev> + <title><ulink url="http://db.cs.berkeley.edu/papers/ERL-M89-17.pdf">The + case for partial indexes</ulink></title> <authorgroup> <author> <firstname>M.</firstname> @@ -471,17 +418,15 @@ [email protected] </biblioset> <biblioset relation="journal"> <title>SIGMOD Record 18(4)</title> - <pagenums>4-11</pagenums> <date>Dec. 1989</date> + <pagenums>4-11</pagenums> </biblioset> </biblioentry> <biblioentry id="STON90a"> <biblioset relation="article"> - <title><ulink url="http://db.cs.berkeley.edu/papers/ERL-M90-34.pdf"> - The implementation of <productname>POSTGRES</productname> - </ulink></title> - <titleabbrev>Stonebraker, Rowe, Hirohama, 1990</titleabbrev> + <title><ulink url="http://db.cs.berkeley.edu/papers/ERL-M90-34.pdf">The + implementation of <productname>POSTGRES</productname></ulink></title> <authorgroup> <author> <firstname>M.</firstname> @@ -508,10 +453,8 @@ [email protected] <biblioentry id="STON90b"> <biblioset relation="article"> - <title><ulink url="http://db.cs.berkeley.edu/papers/ERL-M90-36.pdf"> - On Rules, Procedures, Caching and Views in Database Systems - </ulink></title> - <titleabbrev>Stonebraker et al, ACM, 1990</titleabbrev> + <title><ulink url="http://db.cs.berkeley.edu/papers/ERL-M90-36.pdf">On + Rules, Procedures, Caching and Views in Database Systems</ulink></title> <authorgroup> <author> <firstname>M.</firstname> diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml index f51928513c..ad11109775 100644 --- a/doc/src/sgml/brin.sgml +++ b/doc/src/sgml/brin.sgml @@ -63,7 +63,7 @@ <title>Index Maintenance</title> <para> - At the time of creation, all existing index pages are scanned and a + At the time of creation, all existing heap pages are scanned and a summary index tuple is created for each range, including the possibly-incomplete range at the end. As new pages are filled with data, page ranges that are already @@ -74,9 +74,18 @@ tuple; those tuples remain unsummarized until a summarization run is invoked later, creating initial summaries. This process can be invoked manually using the - <function>brin_summarize_new_values(regclass)</function> function, - or automatically when <command>VACUUM</command> processes the table. + <function>brin_summarize_range(regclass, bigint)</function> or + <function>brin_summarize_new_values(regclass)</function> functions; + automatically when <command>VACUUM</command> processes the table; + or by automatic summarization executed by autovacuum, as insertions + occur. (This last trigger is disabled by default and can be enabled + with the <literal>autosummarize</literal> parameter.) + Conversely, a range can be de-summarized using the + <function>brin_desummarize_range(regclass, bigint)</function> range, + which is useful when the index tuple is no longer a very good + representation because the existing values have changed. </para> + </sect2> </sect1> @@ -282,6 +291,17 @@ </entry> </row> <row> + <entry><literal>macaddr8_minmax_ops</literal></entry> + <entry><type>macaddr8</type></entry> + <entry> + <literal><</literal> + <literal><=</literal> + <literal>=</literal> + <literal>>=</literal> + <literal>></literal> + </entry> + </row> + <row> <entry><literal>name_minmax_ops</literal></entry> <entry><type>name</type></entry> <entry> diff --git a/doc/src/sgml/btree-gin.sgml b/doc/src/sgml/btree-gin.sgml index 2b081db9d5..375e7ec4be 100644 --- a/doc/src/sgml/btree-gin.sgml +++ b/doc/src/sgml/btree-gin.sgml @@ -16,7 +16,8 @@ <type>time without time zone</>, <type>date</>, <type>interval</>, <type>oid</>, <type>money</>, <type>"char"</>, <type>varchar</>, <type>text</>, <type>bytea</>, <type>bit</>, - <type>varbit</>, <type>macaddr</>, <type>inet</>, and <type>cidr</>. + <type>varbit</>, <type>macaddr</>, <type>macaddr8</>, <type>inet</>, + <type>cidr</>, and all <type>enum</> types. </para> <para> diff --git a/doc/src/sgml/btree-gist.sgml b/doc/src/sgml/btree-gist.sgml index 60212c0b5b..966435b697 100644 --- a/doc/src/sgml/btree-gist.sgml +++ b/doc/src/sgml/btree-gist.sgml @@ -16,7 +16,8 @@ <type>time without time zone</>, <type>date</>, <type>interval</>, <type>oid</>, <type>money</>, <type>char</>, <type>varchar</>, <type>text</>, <type>bytea</>, <type>bit</>, - <type>varbit</>, <type>macaddr</>, <type>inet</>, and <type>cidr</>. + <type>varbit</>, <type>macaddr</>, <type>macaddr8</>, <type>inet</>, + <type>cidr</>, <type>uuid</>, and all <type>enum</> types. </para> <para> @@ -106,8 +107,9 @@ INSERT 0 1 <para> Teodor Sigaev (<email>[email protected]</email>), - Oleg Bartunov (<email>[email protected]</email>), and - Janko Richter (<email>[email protected]</email>). See + Oleg Bartunov (<email>[email protected]</email>), + Janko Richter (<email>[email protected]</email>), and + Paul Jungwirth (<email>[email protected]</email>). See <ulink url="http://www.sai.msu.su/~megera/postgres/gist/"></ulink> for additional information. </para> diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 7cce65fe67..7b7ac9ba6f 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -221,6 +221,11 @@ </row> <row> + <entry><link linkend="catalog-pg-partitioned-table"><structname>pg_partitioned_table</structname></link></entry> + <entry>information about partition key of tables</entry> + </row> + + <row> <entry><link linkend="catalog-pg-pltemplate"><structname>pg_pltemplate</structname></link></entry> <entry>template data for procedural languages</entry> </row> @@ -236,6 +241,16 @@ </row> <row> + <entry><link linkend="catalog-pg-publication"><structname>pg_publication</structname></link></entry> + <entry>publications for logical replication</entry> + </row> + + <row> + <entry><link linkend="catalog-pg-publication-rel"><structname>pg_publication_rel</structname></link></entry> + <entry>relation to publication mapping</entry> + </row> + + <row> <entry><link linkend="catalog-pg-range"><structname>pg_range</structname></link></entry> <entry>information about range types</entry> </row> @@ -256,6 +271,11 @@ </row> <row> + <entry><link linkend="catalog-pg-sequence"><structname>pg_sequence</structname></link></entry> + <entry>information about sequences</entry> + </row> + + <row> <entry><link linkend="catalog-pg-shdepend"><structname>pg_shdepend</structname></link></entry> <entry>dependencies on shared objects</entry> </row> @@ -276,6 +296,21 @@ </row> <row> + <entry><link linkend="catalog-pg-statistic-ext"><structname>pg_statistic_ext</structname></link></entry> + <entry>extended planner statistics</entry> + </row> + + <row> + <entry><link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link></entry> + <entry>logical replication subscriptions</entry> + </row> + + <row> + <entry><link linkend="catalog-pg-subscription-rel"><structname>pg_subscription_rel</structname></link></entry> + <entry>relation state for subscriptions</entry> + </row> + + <row> <entry><link linkend="catalog-pg-tablespace"><structname>pg_tablespace</structname></link></entry> <entry>tablespaces within this database cluster</entry> </row> @@ -599,7 +634,7 @@ <row> <entry><structfield>amhandler</structfield></entry> - <entry><type>oid</type></entry> + <entry><type>regproc</type></entry> <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry> <entry> OID of a handler function that is responsible for supplying information @@ -1128,6 +1163,17 @@ </row> <row> + <entry><structfield>attidentity</structfield></entry> + <entry><type>char</type></entry> + <entry></entry> + <entry> + If a zero byte (<literal>''</literal>), then not an identity column. + Otherwise, <literal>a</literal> = generated + always, <literal>d</literal> = generated by default. + </entry> + </row> + + <row> <entry><structfield>attisdropped</structfield></entry> <entry><type>bool</type></entry> <entry></entry> @@ -1342,14 +1388,8 @@ <entry><structfield>rolpassword</structfield></entry> <entry><type>text</type></entry> <entry> - Password (possibly encrypted); null if none. If the password - is encrypted, this column will begin with the string <literal>md5</> - followed by a 32-character hexadecimal MD5 hash. The MD5 hash - will be of the user's password concatenated to their user name. - For example, if user <literal>joe</> has password <literal>xyzzy</>, - <productname>PostgreSQL</> will store the md5 hash of - <literal>xyzzyjoe</>. A password that does not follow that - format is assumed to be unencrypted. + Password (possibly encrypted); null if none. The format depends + on the form of encryption used. </entry> </row> @@ -1363,6 +1403,29 @@ </tgroup> </table> + <para> + For an MD5 encrypted password, <structfield>rolpassword</structfield> + column will begin with the string <literal>md5</> followed by a + 32-character hexadecimal MD5 hash. The MD5 hash will be of the user's + password concatenated to their user name. For example, if user + <literal>joe</> has password <literal>xyzzy</>, <productname>PostgreSQL</> + will store the md5 hash of <literal>xyzzyjoe</>. + </para> + + <para> + If the password is encrypted with SCRAM-SHA-256, it has the format: +<synopsis> +SCRAM-SHA-256$<replaceable><iteration count></>:<replaceable><salt></>$<replaceable><StoredKey></>:<replaceable><ServerKey></> +</synopsis> + where <replaceable>salt</>, <replaceable>StoredKey</> and + <replaceable>ServerKey</> are in Base64 encoded format. This format is + the same as that specified by RFC 5803. + </para> + + <para> + A password that does not follow either of those formats is assumed to be + unencrypted. + </para> </sect1> @@ -1574,7 +1637,8 @@ The catalog <structname>pg_class</structname> catalogs tables and most everything else that has columns or is otherwise similar to a table. This includes indexes (but see also - <structname>pg_index</structname>), sequences, views, materialized + <structname>pg_index</structname>), sequences (but see also + <structname>pg_sequence</structname>), views, materialized views, composite types, and TOAST tables; see <structfield>relkind</>. Below, when we mean all of these kinds of objects we speak of <quote>relations</quote>. Not all @@ -1756,11 +1820,15 @@ <entry><type>char</type></entry> <entry></entry> <entry> - <literal>r</> = ordinary table, <literal>i</> = index, - <literal>S</> = sequence, <literal>v</> = view, + <literal>r</> = ordinary table, + <literal>i</> = index, + <literal>S</> = sequence, + <literal>t</> = TOAST table, + <literal>v</> = view, <literal>m</> = materialized view, - <literal>c</> = composite type, <literal>t</> = TOAST table, - <literal>f</> = foreign table + <literal>c</> = composite type, + <literal>f</> = foreign table, + <literal>p</> = partitioned table </entry> </row> @@ -1873,6 +1941,13 @@ </row> <row> + <entry><structfield>relispartition</structfield></entry> + <entry><type>bool</type></entry> + <entry></entry> + <entry>True if table is a partition</entry> + </row> + + <row> <entry><structfield>relfrozenxid</structfield></entry> <entry><type>xid</type></entry> <entry></entry> @@ -1880,7 +1955,7 @@ All transaction IDs before this one have been replaced with a permanent (<quote>frozen</>) transaction ID in this table. This is used to track whether the table needs to be vacuumed in order to prevent transaction - ID wraparound or to allow <literal>pg_clog</> to be shrunk. Zero + ID wraparound or to allow <literal>pg_xact</> to be shrunk. Zero (<symbol>InvalidTransactionId</symbol>) if the relation is not a table. </entry> </row> @@ -1918,6 +1993,16 @@ Access-method-specific options, as <quote>keyword=value</> strings </entry> </row> + + <row> + <entry><structfield>relpartbound</structfield></entry> + <entry><type>pg_node_tree</type></entry> + <entry></entry> + <entry> + If table is a partition (see <structfield>relispartition</structfield>), + internal representation of the partition bound + </entry> + </row> </tbody> </tgroup> </table> @@ -1993,6 +2078,14 @@ </row> <row> + <entry><structfield>collprovider</structfield></entry> + <entry><type>char</type></entry> + <entry></entry> + <entry>Provider of the collation: <literal>d</literal> = database + default, <literal>c</literal> = libc, <literal>i</literal> = icu</entry> + </row> + + <row> <entry><structfield>collencoding</structfield></entry> <entry><type>int4</type></entry> <entry></entry> @@ -2013,6 +2106,17 @@ <entry></entry> <entry><symbol>LC_CTYPE</> for this collation object</entry> </row> + + <row> + <entry><structfield>collversion</structfield></entry> + <entry><type>text</type></entry> + <entry></entry> + <entry> + Provider-specific version of the collation. This is recorded when the + collation is created and then checked when it is used, to detect + changes in the collation definition that could lead to data corruption. + </entry> + </row> </tbody> </tgroup> </table> @@ -2547,7 +2651,7 @@ All transaction IDs before this one have been replaced with a permanent (<quote>frozen</>) transaction ID in this database. This is used to track whether the database needs to be vacuumed in order to prevent - transaction ID wraparound or to allow <literal>pg_clog</> to be shrunk. + transaction ID wraparound or to allow <literal>pg_xact</> to be shrunk. It is the minimum of the per-table <structname>pg_class</>.<structfield>relfrozenxid</> values. </entry> @@ -4200,6 +4304,7 @@ </table> </sect1> + <sect1 id="catalog-pg-namespace"> <title><structname>pg_namespace</structname></title> @@ -4616,6 +4721,111 @@ </sect1> + <sect1 id="catalog-pg-partitioned-table"> + <title><structname>pg_partitioned_table</structname></title> + + <indexterm zone="catalog-pg-partitioned-table"> + <primary>pg_partitioned_table</primary> + </indexterm> + + <para> + The catalog <structname>pg_partitioned_table</structname> stores + information about how tables are partitioned. + </para> + + <table> + <title><structname>pg_partitioned_table</> Columns</title> + + <tgroup cols="4"> + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>References</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + + <row> + <entry><structfield>partrelid</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry> + <entry>The OID of the <structname>pg_class</> entry for this partitioned table</entry> + </row> + + <row> + <entry><structfield>partstrat</structfield></entry> + <entry><type>char</type></entry> + <entry></entry> + <entry> + Partitioning strategy; <literal>l</> = list partitioned table, + <literal>r</> = range partitioned table + </entry> + </row> + + <row> + <entry><structfield>partnatts</structfield></entry> + <entry><type>int2</type></entry> + <entry></entry> + <entry>The number of columns in partition key</entry> + </row> + + <row> + <entry><structfield>partattrs</structfield></entry> + <entry><type>int2vector</type></entry> + <entry><literal><link linkend="catalog-pg-attribute"><structname>pg_attribute</structname></link>.attnum</literal></entry> + <entry> + This is an array of <structfield>partnatts</structfield> values that + indicate which table columns are part of the partition key. For + example, a value of <literal>1 3</literal> would mean that the first + and the third table columns make up the partition key. A zero in this + array indicates that the corresponding partition key column is an + expression, rather than a simple column reference. + </entry> + </row> + + <row> + <entry><structfield>partclass</structfield></entry> + <entry><type>oidvector</type></entry> + <entry><literal><link linkend="catalog-pg-opclass"><structname>pg_opclass</structname></link>.oid</literal></entry> + <entry> + For each column in the partition key, this contains the OID of the + operator class to use. See + <link linkend="catalog-pg-opclass"><structname>pg_opclass</structname></link> for details. + </entry> + </row> + + <row> + <entry><structfield>partcollation</structfield></entry> + <entry><type>oidvector</type></entry> + <entry><literal><link linkend="catalog-pg-opclass"><structname>pg_opclass</structname></link>.oid</literal></entry> + <entry> + For each column in the partition key, this contains the OID of the + the collation to use for partitioning. + </entry> + </row> + + <row> + <entry><structfield>partexprs</structfield></entry> + <entry><type>pg_node_tree</type></entry> + <entry></entry> + <entry> + Expression trees (in <function>nodeToString()</function> + representation) for partition key columns that are not simple column + references. This is a list with one element for each zero + entry in <structfield>partattrs</>. Null if all partition key columns + are simple references. + </entry> + </row> + + </tbody> + </tgroup> + </table> + </sect1> + + <sect1 id="catalog-pg-pltemplate"> <title><structname>pg_pltemplate</structname></title> @@ -4722,6 +4932,7 @@ </sect1> + <sect1 id="catalog-pg-policy"> <title><structname>pg_policy</structname></title> @@ -4781,6 +4992,13 @@ </row> <row> + <entry><structfield>polpermissive</structfield></entry> + <entry><type>boolean</type></entry> + <entry></entry> + <entry>Is the policy permissive or restrictive?</entry> + </row> + + <row> <entry><structfield>polroles</structfield></entry> <entry><type>oid[]</type></entry> <entry><literal><link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.oid</literal></entry> @@ -5164,6 +5382,137 @@ </sect1> + <sect1 id="catalog-pg-publication"> + <title><structname>pg_publication</structname></title> + + <indexterm zone="catalog-pg-publication"> + <primary>pg_publication</primary> + </indexterm> + + <para> + The catalog <structname>pg_publication</structname> contains all + publications created in the database. For more on publications see + <xref linkend="logical-replication-publication">. + </para> + + <table> + <title><structname>pg_publication</structname> Columns</title> + + <tgroup cols="4"> + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>References</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><structfield>oid</structfield></entry> + <entry><type>oid</type></entry> + <entry></entry> + <entry>Row identifier (hidden attribute; must be explicitly selected)</entry> + </row> + + <row> + <entry><structfield>pubname</structfield></entry> + <entry><type>Name</type></entry> + <entry></entry> + <entry>Name of the publication</entry> + </row> + + <row> + <entry><structfield>pubowner</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.oid</literal></entry> + <entry>Owner of the publication</entry> + </row> + + <row> + <entry><structfield>puballtables</structfield></entry> + <entry><type>bool</type></entry> + <entry></entry> + <entry>If true, this publication automatically includes all tables + in the database, including any that will be created in the future. + </entry> + </row> + + <row> + <entry><structfield>pubinsert</structfield></entry> + <entry><type>bool</type></entry> + <entry></entry> + <entry>If true, <command>INSERT</command> operations are replicated for + tables in the publication.</entry> + </row> + + <row> + <entry><structfield>pubupdate</structfield></entry> + <entry><type>bool</type></entry> + <entry></entry> + <entry>If true, <command>UPDATE</command> operations are replicated for + tables in the publication.</entry> + </row> + + <row> + <entry><structfield>pubdelete</structfield></entry> + <entry><type>bool</type></entry> + <entry></entry> + <entry>If true, <command>DELETE</command> operations are replicated for + tables in the publication.</entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + + <sect1 id="catalog-pg-publication-rel"> + <title><structname>pg_publication_rel</structname></title> + + <indexterm zone="catalog-pg-publication-rel"> + <primary>pg_publication_rel</primary> + </indexterm> + + <para> + The catalog <structname>pg_publication_rel</structname> contains the + mapping between relations and publications in the database. This is a + many-to-many mapping. See also <xref linkend="view-pg-publication-tables"> + for a more user-friendly view of this information. + </para> + + <table> + <title><structname>pg_publication_rel</structname> Columns</title> + + <tgroup cols="4"> + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>References</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><structfield>prpubid</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-publication"><structname>pg_publication</structname></link>.oid</literal></entry> + <entry>Reference to publication</entry> + </row> + + <row> + <entry><structfield>prrelid</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry> + <entry>Reference to relation</entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + <sect1 id="catalog-pg-range"> <title><structname>pg_range</structname></title> @@ -5486,6 +5835,93 @@ </table> </sect1> + <sect1 id="catalog-pg-sequence"> + <title><structname>pg_sequence</structname></title> + + <indexterm zone="catalog-pg-sequence"> + <primary>pg_sequence</primary> + </indexterm> + + <para> + The catalog <structname>pg_sequence</structname> contains information about + sequences. Some of the information about sequences, such as the name and + the schema, is in <structname>pg_class</structname>. + </para> + + <table> + <title><structname>pg_sequence</> Columns</title> + + <tgroup cols="4"> + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>References</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><structfield>seqrelid</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry> + <entry>The OID of the <structname>pg_class</> entry for this sequence</entry> + </row> + + <row> + <entry><structfield>seqtypid</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-type"><structname>pg_type</structname></link>.oid</literal></entry> + <entry>Data type of the sequence</entry> + </row> + + <row> + <entry><structfield>seqstart</structfield></entry> + <entry><type>int8</type></entry> + <entry></entry> + <entry>Start value of the sequence</entry> + </row> + + <row> + <entry><structfield>seqincrement</structfield></entry> + <entry><type>int8</type></entry> + <entry></entry> + <entry>Increment value of the sequence</entry> + </row> + + <row> + <entry><structfield>seqmax</structfield></entry> + <entry><type>int8</type></entry> + <entry></entry> + <entry>Maximum value of the sequence</entry> + </row> + + <row> + <entry><structfield>seqmin</structfield></entry> + <entry><type>int8</type></entry> + <entry></entry> + <entry>Minimum value of the sequence</entry> + </row> + + <row> + <entry><structfield>seqcache</structfield></entry> + <entry><type>int8</type></entry> + <entry></entry> + <entry>Cache size of the sequence</entry> + </row> + + <row> + <entry><structfield>seqcycle</structfield></entry> + <entry><type>bool</type></entry> + <entry></entry> + <entry>Whether the sequence cycles</entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + <sect1 id="catalog-pg-shdepend"> <title><structname>pg_shdepend</structname></title> @@ -5963,6 +6399,305 @@ </sect1> + <sect1 id="catalog-pg-statistic-ext"> + <title><structname>pg_statistic_ext</structname></title> + + <indexterm zone="catalog-pg-statistic-ext"> + <primary>pg_statistic_ext</primary> + </indexterm> + + <para> + The catalog <structname>pg_statistic_ext</structname> + holds extended planner statistics. + Each row in this catalog corresponds to a <firstterm>statistics object</> + created with <xref linkend="sql-createstatistics">. + </para> + + <table> + <title><structname>pg_statistic_ext</> Columns</title> + + <tgroup cols="4"> + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>References</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + + <row> + <entry><structfield>stxrelid</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry> + <entry>Table containing the columns described by this object</entry> + </row> + + <row> + <entry><structfield>stxname</structfield></entry> + <entry><type>name</type></entry> + <entry></entry> + <entry>Name of the statistics object</entry> + </row> + + <row> + <entry><structfield>stxnamespace</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.oid</literal></entry> + <entry> + The OID of the namespace that contains this statistics object + </entry> + </row> + + <row> + <entry><structfield>stxowner</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.oid</literal></entry> + <entry>Owner of the statistics object</entry> + </row> + + <row> + <entry><structfield>stxkeys</structfield></entry> + <entry><type>int2vector</type></entry> + <entry><literal><link linkend="catalog-pg-attribute"><structname>pg_attribute</structname></link>.attnum</literal></entry> + <entry> + An array of attribute numbers, indicating which table columns are + covered by this statistics object; + for example a value of <literal>1 3</literal> would + mean that the first and the third table columns are covered + </entry> + </row> + + <row> + <entry><structfield>stxkind</structfield></entry> + <entry><type>char[]</type></entry> + <entry></entry> + <entry> + An array containing codes for the enabled statistic types; + valid values are: + <literal>d</literal> for n-distinct statistics, + <literal>f</literal> for functional dependency statistics + </entry> + </row> + + <row> + <entry><structfield>stxndistinct</structfield></entry> + <entry><type>pg_ndistinct</type></entry> + <entry></entry> + <entry> + N-distinct counts, serialized as <structname>pg_ndistinct</> type + </entry> + </row> + + <row> + <entry><structfield>stxdependencies</structfield></entry> + <entry><type>pg_dependencies</type></entry> + <entry></entry> + <entry> + Functional dependency statistics, serialized + as <structname>pg_dependencies</> type + </entry> + </row> + + </tbody> + </tgroup> + </table> + + <para> + The <structfield>stxkind</structfield> field is filled at creation of the + statistics object, indicating which statistic type(s) are desired. + The fields after it are initially NULL and are filled only when the + corresponding statistic has been computed by <command>ANALYZE</>. + </para> + </sect1> + + <sect1 id="catalog-pg-subscription"> + <title><structname>pg_subscription</structname></title> + + <indexterm zone="catalog-pg-subscription"> + <primary>pg_subscription</primary> + </indexterm> + + <para> + The catalog <structname>pg_subscription</structname> contains all existing + logical replication subscriptions. For more information about logical + replication see <xref linkend="logical-replication">. + </para> + + <para> + Unlike most system catalogs, <structname>pg_subscription</structname> is + shared across all databases of a cluster: There is only one copy + of <structname>pg_subscription</structname> per cluster, not one per + database. + </para> + + <para> + Access to the column <structfield>subconninfo</structfield> is revoked from + normal users, because it could contain plain-text passwords. + </para> + + <table> + <title><structname>pg_subscription</structname> Columns</title> + + <tgroup cols="4"> + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>References</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><structfield>oid</structfield></entry> + <entry><type>oid</type></entry> + <entry></entry> + <entry>Row identifier (hidden attribute; must be explicitly selected)</entry> + </row> + + <row> + <entry><structfield>subdbid</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-database"><structname>pg_database</structname></link>.oid</literal></entry> + <entry>OID of the database which the subscription resides in</entry> + </row> + + <row> + <entry><structfield>subname</structfield></entry> + <entry><type>name</type></entry> + <entry></entry> + <entry>Name of the subscription</entry> + </row> + + <row> + <entry><structfield>subowner</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.oid</literal></entry> + <entry>Owner of the subscription</entry> + </row> + + <row> + <entry><structfield>subenabled</structfield></entry> + <entry><type>bool</type></entry> + <entry></entry> + <entry>If true, the subscription is enabled and should be replicating.</entry> + </row> + + <row> + <entry><structfield>subsynccommit</structfield></entry> + <entry><type>text</type></entry> + <entry></entry> + <entry> + Contains the value of the <varname>synchronous_commit</varname> + setting for the subscription workers. + </entry> + </row> + + <row> + <entry><structfield>subconninfo</structfield></entry> + <entry><type>text</type></entry> + <entry></entry> + <entry>Connection string to the upstream database</entry> + </row> + + <row> + <entry><structfield>subslotname</structfield></entry> + <entry><type>name</type></entry> + <entry></entry> + <entry>Name of the replication slot in the upstream database. Also used + for local replication origin name.</entry> + </row> + + <row> + <entry><structfield>subpublications</structfield></entry> + <entry><type>text[]</type></entry> + <entry></entry> + <entry>Array of subscribed publication names. These reference the + publications on the publisher server. For more on publications + see <xref linkend="logical-replication-publication">. + </entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + + <sect1 id="catalog-pg-subscription-rel"> + <title><structname>pg_subscription_rel</structname></title> + + <indexterm zone="catalog-pg-subscription-rel"> + <primary>pg_subscription_rel</primary> + </indexterm> + + <para> + The catalog <structname>pg_subscription_rel</structname> contains the + state for each replicated relation in each subscription. This is a + many-to-many mapping. + </para> + + <para> + This catalog only contains tables known to the subscription after running + either <command>CREATE SUBSCRIPTION</command> or + <command>ALTER SUBSCRIPTION ... REFRESH</command>. + </para> + + <table> + <title><structname>pg_subscription_rel</structname> Columns</title> + + <tgroup cols="4"> + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>References</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><structfield>srsubid</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>.oid</literal></entry> + <entry>Reference to subscription</entry> + </row> + + <row> + <entry><structfield>srrelid</structfield></entry> + <entry><type>oid</type></entry> + <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry> + <entry>Reference to relation</entry> + </row> + + <row> + <entry><structfield>srsubstate</structfield></entry> + <entry><type>char</type></entry> + <entry></entry> + <entry> + State code: + <literal>i</> = initialize, + <literal>d</> = data is being copied, + <literal>s</> = synchronized, + <literal>r</> = ready (normal replication) + </entry> + </row> + + <row> + <entry><structfield>srsublsn</structfield></entry> + <entry><type>pg_lsn</type></entry> + <entry></entry> + <entry> + End LSN for <literal>s</> and <literal>r</> states. + </entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> <sect1 id="catalog-pg-tablespace"> <title><structname>pg_tablespace</structname></title> @@ -6264,6 +6999,22 @@ representation) for the trigger's <literal>WHEN</> condition, or null if none</entry> </row> + + <row> + <entry><structfield>tgoldtable</structfield></entry> + <entry><type>name</type></entry> + <entry></entry> + <entry><literal>REFERENCING</> clause name for <literal>OLD TABLE</>, + or null if none</entry> + </row> + + <row> + <entry><structfield>tgnewtable</structfield></entry> + <entry><type>name</type></entry> + <entry></entry> + <entry><literal>REFERENCING</> clause name for <literal>NEW TABLE</>, + or null if none</entry> + </row> </tbody> </tgroup> </table> @@ -7579,6 +8330,11 @@ </row> <row> + <entry><link linkend="view-pg-hba-file-rules"><structname>pg_hba_file_rules</structname></link></entry> + <entry>summary of client authentication configuration file contents</entry> + </row> + + <row> <entry><link linkend="view-pg-indexes"><structname>pg_indexes</structname></link></entry> <entry>indexes</entry> </row> @@ -7609,6 +8365,11 @@ </row> <row> + <entry><link linkend="view-pg-publication-tables"><structname>pg_publication_tables</structname></link></entry> + <entry>publications and their associated tables</entry> + </row> + + <row> <entry><link linkend="view-pg-replication-origin-status"><structname>pg_replication_origin_status</structname></link></entry> <entry>information about replication origins, including replication progress</entry> </row> @@ -7634,6 +8395,11 @@ </row> <row> + <entry><link linkend="view-pg-sequences"><structname>pg_sequences</structname></link></entry> + <entry>sequences</entry> + </row> + + <row> <entry><link linkend="view-pg-settings"><structname>pg_settings</structname></link></entry> <entry>parameter settings</entry> </row> @@ -7851,6 +8617,11 @@ application. </para> + <para> + By default, the <structname>pg_config</structname> view can be read + only by superusers. + </para> + <table> <title><structname>pg_config</> Columns</title> <tgroup cols="3"> @@ -8026,8 +8797,8 @@ </para> <para> - The <structname>pg_file_settings</structname> view can be read only by - superusers. + By default, the <structname>pg_file_settings</structname> view can be read + only by superusers. </para> <table> @@ -8163,6 +8934,114 @@ </sect1> + <sect1 id="view-pg-hba-file-rules"> + <title><structname>pg_hba_file_rules</structname></title> + + <indexterm zone="view-pg-hba-file-rules"> + <primary>pg_hba_file_rules</primary> + </indexterm> + + <para> + The view <structname>pg_hba_file_rules</structname> provides a summary of + the contents of the client authentication configuration + file, <filename>pg_hba.conf</>. A row appears in this view for each + non-empty, non-comment line in the file, with annotations indicating + whether the rule could be applied successfully. + </para> + + <para> + This view can be helpful for checking whether planned changes in the + authentication configuration file will work, or for diagnosing a previous + failure. Note that this view reports on the <emphasis>current</> contents + of the file, not on what was last loaded by the server. + </para> + + <para> + By default, the <structname>pg_hba_file_rules</structname> view can be read + only by superusers. + </para> + + <table> + <title><structname>pg_hba_file_rules</> Columns</title> + + <tgroup cols="3"> + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><structfield>line_number</structfield></entry> + <entry><structfield>integer</structfield></entry> + <entry> + Line number of this rule in <filename>pg_hba.conf</> + </entry> + </row> + <row> + <entry><structfield>type</structfield></entry> + <entry><structfield>text</structfield></entry> + <entry>Type of connection</entry> + </row> + <row> + <entry><structfield>database</structfield></entry> + <entry><structfield>text[]</structfield></entry> + <entry>List of database name(s) to which this rule applies</entry> + </row> + <row> + <entry><structfield>user_name</structfield></entry> + <entry><structfield>text[]</structfield></entry> + <entry>List of user and group name(s) to which this rule applies</entry> + </row> + <row> + <entry><structfield>address</structfield></entry> + <entry><structfield>text</structfield></entry> + <entry> + Host name or IP address, or one + of <literal>all</literal>, <literal>samehost</literal>, + or <literal>samenet</literal>, or null for local connections + </entry> + </row> + <row> + <entry><structfield>netmask</structfield></entry> + <entry><structfield>text</structfield></entry> + <entry>IP address mask, or null if not applicable</entry> + </row> + <row> + <entry><structfield>auth_method</structfield></entry> + <entry><type>text</type></entry> + <entry>Authentication method</entry> + </row> + <row> + <entry><structfield>options</structfield></entry> + <entry><type>text[]</type></entry> + <entry>Options specified for authentication method, if any</entry> + </row> + <row> + <entry><structfield>error</structfield></entry> + <entry><structfield>text</structfield></entry> + <entry> + If not null, an error message indicating why this + line could not be processed + </entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + Usually, a row reflecting an incorrect entry will have values for only + the <structfield>line_number</> and <structfield>error</> fields. + </para> + + <para> + See <xref linkend="client-authentication"> for more information about + client authentication configuration. + </para> + </sect1> + <sect1 id="view-pg-indexes"> <title><structname>pg_indexes</structname></title> @@ -8667,6 +9546,12 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx <entry>Name of policy</entry> </row> <row> + <entry><structfield>polpermissive</structfield></entry> + <entry><type>text</type></entry> + <entry></entry> + <entry>Is the policy permissive or restrictive?</entry> + </row> + <row> <entry><structfield>roles</structfield></entry> <entry><type>name[]</type></entry> <entry></entry> @@ -8874,6 +9759,61 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx </sect1> + <sect1 id="view-pg-publication-tables"> + <title><structname>pg_publication_tables</structname></title> + + <indexterm zone="view-pg-publication-tables"> + <primary>pg_publication_tables</primary> + </indexterm> + + <para> + The view <structname>pg_publication_tables</structname> provides + information about the mapping between publications and the tables they + contain. Unlike the underlying + catalog <structname>pg_publication_rel</structname>, this view expands + publications defined as <literal>FOR ALL TABLES</literal>, so for such + publications there will be a row for each eligible table. + </para> + + <table> + <title><structname>pg_publication_tables</structname> Columns</title> + + <tgroup cols="4"> + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>References</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><structfield>pubname</structfield></entry> + <entry><type>name</type></entry> + <entry><literal><link linkend="catalog-pg-publication"><structname>pg_publication</structname></link>.pubname</literal></entry> + <entry>Name of publication</entry> + </row> + + <row> + <entry><structfield>schemaname</structfield></entry> + <entry><type>name</type></entry> + <entry><literal><link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.nspname</literal></entry> + <entry>Name of schema containing table</entry> + </row> + + <row> + <entry><structfield>tablename</structfield></entry> + <entry><type>name</type></entry> + <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.relname</literal></entry> + <entry>Name of table</entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + <sect1 id="view-pg-replication-origin-status"> <title><structname>pg_replication_origin_status</structname></title> @@ -9010,6 +9950,15 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx </row> <row> + <entry><structfield>temporary</structfield></entry> + <entry><type>boolean</type></entry> + <entry></entry> + <entry>True if this is a temporary replication slot. Temporary slots are + not saved to disk and are automatically dropped on error or when + the session has finished.</entry> + </row> + + <row> <entry><structfield>active</structfield></entry> <entry><type>boolean</type></entry> <entry></entry> @@ -9369,6 +10318,107 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx </table> </sect1> + <sect1 id="view-pg-sequences"> + <title><structname>pg_sequences</structname></title> + + <indexterm zone="view-pg-sequences"> + <primary>pg_sequences</primary> + </indexterm> + + <para> + The view <structname>pg_sequences</structname> provides access to + useful information about each sequence in the database. + </para> + + <table> + <title><structname>pg_sequences</> Columns</title> + + <tgroup cols="4"> + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>References</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><structfield>schemaname</structfield></entry> + <entry><type>name</type></entry> + <entry><literal><link linkend="catalog-pg-namespace"><structname>pg_namespace</structname></link>.nspname</literal></entry> + <entry>Name of schema containing sequence</entry> + </row> + <row> + <entry><structfield>sequencename</structfield></entry> + <entry><type>name</type></entry> + <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.relname</literal></entry> + <entry>Name of sequence</entry> + </row> + <row> + <entry><structfield>sequenceowner</structfield></entry> + <entry><type>name</type></entry> + <entry><literal><link linkend="catalog-pg-authid"><structname>pg_authid</structname></link>.rolname</literal></entry> + <entry>Name of sequence's owner</entry> + </row> + <row> + <entry><structfield>data_type</structfield></entry> + <entry><type>regtype</type></entry> + <entry><literal><link linkend="catalog-pg-authid"><structname>pg_type</structname></link>.oid</literal></entry> + <entry>Data type of the sequence</entry> + </row> + <row> + <entry><structfield>start_value</structfield></entry> + <entry><type>bigint</type></entry> + <entry></entry> + <entry>Start value of the sequence</entry> + </row> + <row> + <entry><structfield>min_value</structfield></entry> + <entry><type>bigint</type></entry> + <entry></entry> + <entry>Minimum value of the sequence</entry> + </row> + <row> + <entry><structfield>max_value</structfield></entry> + <entry><type>bigint</type></entry> + <entry></entry> + <entry>Maximum value of the sequence</entry> + </row> + <row> + <entry><structfield>increment_by</structfield></entry> + <entry><type>bigint</type></entry> + <entry></entry> + <entry>Increment value of the sequence</entry> + </row> + <row> + <entry><structfield>cycle</structfield></entry> + <entry><type>boolean</type></entry> + <entry></entry> + <entry>Whether the sequence cycles</entry> + </row> + <row> + <entry><structfield>cache_size</structfield></entry> + <entry><type>bigint</type></entry> + <entry></entry> + <entry>Cache size of the sequence</entry> + </row> + <row> + <entry><structfield>last_value</structfield></entry> + <entry><type>bigint</type></entry> + <entry></entry> + <entry>The last sequence value written to disk. If caching is used, + this value can be greater than the last value handed out from the + sequence. Null if the sequence has not been read from yet. Also, if + the current user does not have <literal>USAGE</literal> + or <literal>SELECT</literal> privilege on the sequence, the value is + null.</entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + <sect1 id="view-pg-settings"> <title><structname>pg_settings</structname></title> @@ -9480,15 +10530,17 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx <entry><type>text</type></entry> <entry>Configuration file the current value was set in (null for values set from sources other than configuration files, or when - examined by a non-superuser); - helpful when using <literal>include</> directives in configuration files</entry> + examined by a user who is neither a superuser or a member of + <literal>pg_read_all_settings</literal>); helpful when using + <literal>include</> directives in configuration files</entry> </row> <row> <entry><structfield>sourceline</structfield></entry> <entry><type>integer</type></entry> <entry>Line number within the configuration file the current value was set at (null for values set from sources other than configuration files, - or when examined by a non-superuser) + or when examined by a user who is neither a superuser or a member of + <literal>pg_read_all_settings</literal>). </entry> </row> <row> @@ -10066,6 +11118,13 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx </tgroup> </table> + <para> + While most timezone abbreviations represent fixed offsets from UTC, + there are some that have historically varied in value + (see <xref linkend="datetime-config-files"> for more information). + In such cases this view presents their current meaning. + </para> + </sect1> <sect1 id="view-pg-timezone-names"> @@ -10294,8 +11353,11 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx <entry></entry> <entry> User mapping specific options, as <quote>keyword=value</> - strings, if the current user is the owner of the foreign - server, else null + strings. This column will show as null unless the current user + is the user being mapped, or the mapping is for + <literal>PUBLIC</literal> and the current user is the server + owner, or the current user is a superuser. The intent is + to protect password information stored as user mapping option. </entry> </row> </tbody> diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml index f8c7ac3b16..5e0a0bf7a7 100644 --- a/doc/src/sgml/charset.sgml +++ b/doc/src/sgml/charset.sgml @@ -496,25 +496,51 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR"; </para> </sect2> - <sect2> + <sect2 id="collation-managing"> <title>Managing Collations</title> <para> - A collation is an SQL schema object that maps an SQL name to - operating system locales. In particular, it maps to a combination - of <symbol>LC_COLLATE</symbol> and <symbol>LC_CTYPE</symbol>. (As + A collation is an SQL schema object that maps an SQL name to locales + provided by libraries installed in the operating system. A collation + definition has a <firstterm>provider</firstterm> that specifies which + library supplies the locale data. One standard provider name + is <literal>libc</literal>, which uses the locales provided by the + operating system C library. These are the locales that most tools + provided by the operating system use. Another provider + is <literal>icu</literal>, which uses the external + ICU<indexterm><primary>ICU</></> library. Support for ICU has to be + configured when PostgreSQL is built. + </para> + + <para> + A collation object provided by <literal>libc</literal> maps to a + combination of <symbol>LC_COLLATE</symbol> and <symbol>LC_CTYPE</symbol> + settings. (As the name would suggest, the main purpose of a collation is to set <symbol>LC_COLLATE</symbol>, which controls the sort order. But it is rarely necessary in practice to have an <symbol>LC_CTYPE</symbol> setting that is different from <symbol>LC_COLLATE</symbol>, so it is more convenient to collect these under one concept than to create another infrastructure for - setting <symbol>LC_CTYPE</symbol> per expression.) Also, a collation + setting <symbol>LC_CTYPE</symbol> per expression.) Also, + a <literal>libc</literal> collation is tied to a character set encoding (see <xref linkend="multibyte">). The same collation name may exist for different encodings. </para> <para> + A collation provided by <literal>icu</literal> maps to a named collator + provided by the ICU library. ICU does not support + separate <quote>collate</quote> and <quote>ctype</quote> settings, so they + are always the same. Also, ICU collations are independent of the + encoding, so there is always only one ICU collation for a given name in a + database. + </para> + + <sect3> + <title>Standard Collations</title> + + <para> On all platforms, the collations named <literal>default</>, <literal>C</>, and <literal>POSIX</> are available. Additional collations may be available depending on operating system support. @@ -528,12 +554,36 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR"; </para> <para> + Additionally, the SQL standard collation name <literal>ucs_basic</literal> + is available for encoding <literal>UTF8</literal>. It is equivalent + to <literal>C</literal> and sorts by Unicode code point. + </para> + </sect3> + + <sect3> + <title>Predefined Collations</title> + + <para> If the operating system provides support for using multiple locales within a single program (<function>newlocale</> and related functions), + or support for ICU is configured, then when a database cluster is initialized, <command>initdb</command> populates the system catalog <literal>pg_collation</literal> with collations based on all the locales it finds on the operating - system at the time. For example, the operating system might + system at the time. + </para> + + <para> + To inspect the currently available locales, use the query <literal>SELECT + * FROM pg_collation</literal>, or the command <command>\dOS+</command> + in <application>psql</application>. + </para> + + <sect4> + <title>libc collations</title> + + <para> + For example, the operating system might provide a locale named <literal>de_DE.utf8</literal>. <command>initdb</command> would then create a collation named <literal>de_DE.utf8</literal> for encoding <literal>UTF8</literal> @@ -548,13 +598,14 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR"; </para> <para> - In case a collation is needed that has different values for - <symbol>LC_COLLATE</symbol> and <symbol>LC_CTYPE</symbol>, a new - collation may be created using - the <xref linkend="sql-createcollation"> command. That command - can also be used to create a new collation from an existing - collation, which can be useful to be able to use - operating-system-independent collation names in applications. + The default set of collations provided by <literal>libc</literal> map + directly to the locales installed in the operating system, which can be + listed using the command <literal>locale -a</literal>. In case + a <literal>libc</literal> collation is needed that has different values + for <symbol>LC_COLLATE</symbol> and <symbol>LC_CTYPE</symbol>, or new + locales are installed in the operating system after the database system + was initialized, then a new collation may be created using + the <xref linkend="sql-createcollation"> command. </para> <para> @@ -566,8 +617,8 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR"; Use of the stripped collation names is recommended, since it will make one less thing you need to change if you decide to change to another database encoding. Note however that the <literal>default</>, - <literal>C</>, and <literal>POSIX</> collations can be used - regardless of the database encoding. + <literal>C</>, and <literal>POSIX</> collations, as well as all collations + provided by ICU can be used regardless of the database encoding. </para> <para> @@ -581,6 +632,105 @@ SELECT a COLLATE "C" < b COLLATE "POSIX" FROM test1; collations have identical behaviors. Mixing stripped and non-stripped collation names is therefore not recommended. </para> + </sect4> + + <sect4> + <title>ICU collations</title> + + <para> + Collations provided by ICU are created with names in BCP 47 language tag + format, with a <quote>private use</quote> + extension <literal>-x-icu</literal> appended, to distinguish them from + libc locales. So <literal>de-x-icu</literal> would be an example. + </para> + + <para> + With ICU, it is not sensible to enumerate all possible locale names. ICU + uses a particular naming system for locales, but there are many more ways + to name a locale than there are actually distinct locales. (In fact, any + string will be accepted as a locale name.) + See <ulink url="http://userguide.icu-project.org/locale"></ulink> for + information on ICU locale naming. <command>initdb</command> uses the ICU + APIs to extract a set of locales with distinct collation rules to populate + the initial set of collations. Here are some examples collations that + might be created: + + <variablelist> + <varlistentry> + <term><literal>de-x-icu</literal></term> + <listitem> + <para>German collation, default variant</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>de-u-co-phonebk-x-icu</literal></term> + <listitem> + <para>German collation, phone book variant</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>de-AT-x-icu</literal></term> + <listitem> + <para>German collation for Austria, default variant</para> + <para> + (Note that as of this writing, there is no, + say, <literal>de-DE-x-icu</literal> or <literal>de-CH-x-icu</literal>, + because those are equivalent to <literal>de-x-icu</literal>.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>de-AT-u-co-phonebk-x-icu</literal></term> + <listitem> + <para>German collation for Austria, phone book variant</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>und-x-icu</literal> (for <quote>undefined</quote>)</term> + <listitem> + <para> + ICU <quote>root</quote> collation. Use this to get a reasonable + language-agnostic sort order. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + Some (less frequently used) encodings are not supported by ICU. If the + database cluster was initialized with such an encoding, no ICU collations + will be predefined. + </para> + </sect4> + </sect3> + + <sect3> + <title>Copying Collations</title> + + <para> + The command <xref linkend="sql-createcollation"> can also be used to + create a new collation from an existing collation, which can be useful to + be able to use operating-system-independent collation names in + applications, create compatibility names, or use an ICU-provided collation + under a more readable name. For example: +<programlisting> +CREATE COLLATION german FROM "de_DE"; +CREATE COLLATION french FROM "fr-x-icu"; +CREATE COLLATION "de-DE-x-icu" FROM "de-x-icu"; +</programlisting> + </para> + + <para> + The standard and predefined collations are in the + schema <literal>pg_catalog</literal>, like all predefined objects. + User-defined collations should be created in user schemas. This also + ensures that they are saved by <command>pg_dump</command>. + </para> + </sect3> </sect2> </sect1> diff --git a/doc/src/sgml/citext.sgml b/doc/src/sgml/citext.sgml index 949e22876e..c70579cea4 100644 --- a/doc/src/sgml/citext.sgml +++ b/doc/src/sgml/citext.sgml @@ -131,6 +131,11 @@ SELECT * FROM users WHERE nick = 'Larry'; <itemizedlist> <listitem> <para> + <function>regexp_match()</> + </para> + </listitem> + <listitem> + <para> <function>regexp_matches()</> </para> </listitem> diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index ca262d9452..819db811b2 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -156,9 +156,11 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <para> To make use of this option the server must be built with <acronym>SSL</acronym> support. Furthermore, - <acronym>SSL</acronym> must be enabled at server start time + <acronym>SSL</acronym> must be enabled by setting the <xref linkend="guc-ssl"> configuration parameter (see <xref linkend="ssl-tcp"> for more information). + Otherwise, the <literal>hostssl</literal> record is ignored except for + logging a warning that it cannot match any connections. </para> </listitem> </varlistentry> @@ -191,7 +193,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> members of the role, directly or indirectly, and not just by virtue of being a superuser. The value <literal>replication</> specifies that the record - matches if a replication connection is requested (note that + matches if a physical replication connection is requested (note that replication connections do not specify any particular database). Otherwise, this is the name of a specific <productname>PostgreSQL</productname> database. @@ -410,12 +412,22 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> </varlistentry> <varlistentry> + <term><literal>scram-sha-256</></term> + <listitem> + <para> + Perform SCRAM-SHA-256 authentication to verify the user's + password. See <xref linkend="auth-password"> for details. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><literal>md5</></term> <listitem> <para> - Require the client to supply a double-MD5-hashed password for - authentication. - See <xref linkend="auth-password"> for details. + Perform SCRAM-SHA-256 or MD5 authentication to verify the + user's password. See <xref linkend="auth-password"> + for details. </para> </listitem> </varlistentry> @@ -595,6 +607,24 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> re-read the file. </para> + <note> + <para> + The preceding statement is not true on Microsoft Windows: there, any + changes in the <filename>pg_hba.conf</filename> file are immediately + applied by subsequent new connections. + </para> + </note> + + <para> + The system view + <link linkend="view-pg-hba-file-rules"><structname>pg_hba_file_rules</structname></link> + can be helpful for pre-testing changes to the <filename>pg_hba.conf</> + file, or for diagnosing problems if loading of the file did not have the + desired effects. Rows in the view with + non-null <structfield>error</structfield> fields indicate problems in the + corresponding lines of the file. + </para> + <tip> <para> To connect to a particular database, a user must not only pass the @@ -653,13 +683,18 @@ host postgres all 192.168.93.0/24 ident # "postgres" if the user's password is correctly supplied. # # TYPE DATABASE USER ADDRESS METHOD -host postgres all 192.168.12.10/32 md5 +host postgres all 192.168.12.10/32 scram-sha-256 # Allow any user from hosts in the example.com domain to connect to # any database if the user's password is correctly supplied. # +# Require SCRAM authentication for most users, but make an exception +# for user 'mike', who uses an older client that doesn't support SCRAM +# authentication. +# # TYPE DATABASE USER ADDRESS METHOD -host all all .example.com md5 +host all mike .example.com md5 +host all all .example.com scram-sha-256 # In the absence of preceding "host" lines, these two lines will # reject all connections from 192.168.54.1 (since that entry will be @@ -711,7 +746,7 @@ local db1,db2,@demodbs all md5 <para> When using an external authentication system such as Ident or GSSAPI, the name of the operating system user that initiated the connection - might not be the same as the database user that is to be connect as. + might not be the same as the database user (role) that is to be used. In this case, a user name map can be applied to map the operating system user name to a database user. To use user name mapping, specify <literal>map</literal>=<replaceable>map-name</replaceable> @@ -887,21 +922,39 @@ omicron bryanh guest1 </indexterm> <para> - The password-based authentication methods are <literal>md5</> - and <literal>password</>. These methods operate + The password-based authentication methods are <literal>scram-sha-256</>, + <literal>md5</>, and <literal>password</>. These methods operate similarly except for the way that the password is sent across the - connection, namely MD5-hashed and clear-text respectively. + connection. + </para> + + <para> + Plain <literal>password</> sends the password in clear-text, and is + therefore vulnerable to password <quote>sniffing</> attacks. It should + always be avoided if possible. If the connection is protected by SSL + encryption then <literal>password</> can be used safely, though. + (Though SSL certificate authentication might be a better choice if one + is depending on using SSL). + </para> + + + <para> + <literal>scram-sha-256</> performs SCRAM-SHA-256 authentication, as + described in + <ulink url="https://tools.ietf.org/html/rfc5802">RFC5802</ulink>. It + is a challenge-response scheme, that prevents password sniffing on + untrusted connections. It is more secure than the <literal>md5</> + method, but might not be supported by older clients. </para> <para> - If you are at all concerned about password - <quote>sniffing</> attacks then <literal>md5</> is preferred. - Plain <literal>password</> should always be avoided if possible. - However, <literal>md5</> cannot be used with the <xref - linkend="guc-db-user-namespace"> feature. If the connection is - protected by SSL encryption then <literal>password</> can be used - safely (though SSL certificate authentication might be a better - choice if one is depending on using SSL). + <literal>md5</> allows falling back to a less secure challenge-response + mechanism for those users with an MD5 hashed password. + The fallback mechanism also prevents password sniffing, but provides no + protection if an attacker manages to steal the password hash from the + server, and it cannot be used with the <xref + linkend="guc-db-user-namespace"> feature. For all other users, + <literal>md5</> works the same as <literal>scram-sha-256</>. </para> <para> @@ -1306,7 +1359,7 @@ omicron bryanh guest1 socket parameter, or similar mechanisms. Currently that includes <systemitem class="osname">Linux</>, most flavors of <systemitem class="osname">BSD</> including - <systemitem class="osname">OS X</>, + <systemitem class="osname">macOS</>, and <systemitem class="osname">Solaris</systemitem>. </para> @@ -1569,23 +1622,35 @@ host ... ldap ldapurl="ldap://ldap.example.net/dc=example,dc=net?uid?sub" </para> <para> + Multiple RADIUS servers can be specified, in which case they will + be tried sequentially. If a negative response is received from + a server, the authentication will fail. If no response is received, + the next server in the list will be tried. To specify multiple + servers, put the names within quotes and separate the server names + with a comma. If multiple servers are specified, all other RADIUS + options can also be given as a comma separate list, to apply + individual values to each server. They can also be specified as + a single value, in which case this value will apply to all servers. + </para> + + <para> The following configuration options are supported for RADIUS: <variablelist> <varlistentry> - <term><literal>radiusserver</literal></term> + <term><literal>radiusservers</literal></term> <listitem> <para> - The name or IP address of the RADIUS server to connect to. + The name or IP addresses of the RADIUS servers to connect to. This parameter is required. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>radiussecret</literal></term> + <term><literal>radiussecrets</literal></term> <listitem> <para> - The shared secret used when talking securely to the RADIUS + The shared secrets used when talking securely to the RADIUS server. This must have exactly the same value on the PostgreSQL and RADIUS servers. It is recommended that this be a string of at least 16 characters. This parameter is required. @@ -1603,17 +1668,17 @@ host ... ldap ldapurl="ldap://ldap.example.net/dc=example,dc=net?uid?sub" </varlistentry> <varlistentry> - <term><literal>radiusport</literal></term> + <term><literal>radiusports</literal></term> <listitem> <para> - The port number on the RADIUS server to connect to. If no port + The port number on the RADIUS servers to connect to. If no port is specified, the default port <literal>1812</> will be used. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>radiusidentifier</literal></term> + <term><literal>radiusidentifiers</literal></term> <listitem> <para> The string used as <literal>NAS Identifier</> in the RADIUS diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index e2b08f6b4a..b7c3ca8412 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -533,10 +533,10 @@ include_dir 'conf.d' </term> <listitem> <para> - Specifies the configuration file for - <xref linkend="auth-username-maps"> user name mapping + Specifies the configuration file for user name mapping (customarily called <filename>pg_ident.conf</>). This parameter can only be set at server start. + See also <xref linkend="auth-username-maps">. </para> </listitem> </varlistentry> @@ -971,10 +971,10 @@ include_dir 'conf.d' <listitem> <para> Enables <acronym>SSL</> connections. Please read - <xref linkend="ssl-tcp"> before using this. The default - is <literal>off</>. This parameter can only be set at server - start. <acronym>SSL</> communication is only possible with - TCP/IP connections. + <xref linkend="ssl-tcp"> before using this. + This parameter can only be set in the <filename>postgresql.conf</> + file or on the server command line. + The default is <literal>off</>. </para> </listitem> </varlistentry> @@ -988,11 +988,16 @@ include_dir 'conf.d' <listitem> <para> Specifies the name of the file containing the SSL server certificate - authority (CA). The default is empty, meaning no CA file is loaded, - and client certificate verification is not performed. (In previous - releases of PostgreSQL, the name of this file was hard-coded - as <filename>root.crt</filename>.) Relative paths are relative to the - data directory. This parameter can only be set at server start. + authority (CA). + Relative paths are relative to the data directory. + This parameter can only be set in the <filename>postgresql.conf</> + file or on the server command line. + The default is empty, meaning no CA file is loaded, + and client certificate verification is not performed. + </para> + <para> + In previous releases of PostgreSQL, the name of this file was + hard-coded as <filename>root.crt</filename>. </para> </listitem> </varlistentry> @@ -1006,9 +1011,10 @@ include_dir 'conf.d' <listitem> <para> Specifies the name of the file containing the SSL server certificate. - The default is <filename>server.crt</filename>. Relative paths are - relative to the data directory. This parameter can only be set at - server start. + Relative paths are relative to the data directory. + This parameter can only be set in the <filename>postgresql.conf</> + file or on the server command line. + The default is <filename>server.crt</filename>. </para> </listitem> </varlistentry> @@ -1022,11 +1028,15 @@ include_dir 'conf.d' <listitem> <para> Specifies the name of the file containing the SSL server certificate - revocation list (CRL). The default is empty, meaning no CRL file is - loaded. (In previous releases of PostgreSQL, the name of this file was - hard-coded as <filename>root.crl</filename>.) Relative paths are - relative to the data directory. This parameter can only be set at - server start. + revocation list (CRL). + Relative paths are relative to the data directory. + This parameter can only be set in the <filename>postgresql.conf</> + file or on the server command line. + The default is empty, meaning no CRL file is loaded. + </para> + <para> + In previous releases of PostgreSQL, the name of this file was + hard-coded as <filename>root.crl</filename>. </para> </listitem> </varlistentry> @@ -1040,9 +1050,10 @@ include_dir 'conf.d' <listitem> <para> Specifies the name of the file containing the SSL server private key. - The default is <filename>server.key</filename>. Relative paths are - relative to the data directory. This parameter can only be set at - server start. + Relative paths are relative to the data directory. + This parameter can only be set in the <filename>postgresql.conf</> + file or on the server command line. + The default is <filename>server.key</filename>. </para> </listitem> </varlistentry> @@ -1059,9 +1070,12 @@ include_dir 'conf.d' used on secure connections. See the <citerefentry><refentrytitle>ciphers</></citerefentry> manual page in the <application>OpenSSL</> package for the syntax of this setting - and a list of supported values. The default value is - <literal>HIGH:MEDIUM:+3DES:!aNULL</>. It is usually reasonable, - unless you have specific security requirements. + and a list of supported values. + This parameter can only be set in the <filename>postgresql.conf</> + file or on the server command line. + The default value is <literal>HIGH:MEDIUM:+3DES:!aNULL</>. The + default is usually a reasonable choice unless you have specific + security requirements. </para> <para> @@ -1125,7 +1139,7 @@ include_dir 'conf.d' </varlistentry> <varlistentry id="guc-ssl-prefer-server-ciphers" xreflabel="ssl_prefer_server_ciphers"> - <term><varname>ssl_prefer_server_ciphers</varname> (<type>bool</type>) + <term><varname>ssl_prefer_server_ciphers</varname> (<type>boolean</type>) <indexterm> <primary><varname>ssl_prefer_server_ciphers</> configuration parameter</primary> </indexterm> @@ -1133,7 +1147,10 @@ include_dir 'conf.d' <listitem> <para> Specifies whether to use the server's SSL cipher preferences, rather - than the client's. The default is true. + than the client's. + This parameter can only be set in the <filename>postgresql.conf</> + file or on the server command line. + The default is <literal>true</>. </para> <para> @@ -1156,18 +1173,18 @@ include_dir 'conf.d' <para> Specifies the name of the curve to use in <acronym>ECDH</> key exchange. It needs to be supported by all clients that connect. - It does not need to be same curve as used by server's Elliptic - Curve key. The default is <literal>prime256v1</>. + It does not need to be the same curve used by the server's Elliptic + Curve key. + This parameter can only be set in the <filename>postgresql.conf</> + file or on the server command line. + The default is <literal>prime256v1</>. </para> <para> - OpenSSL names for most common curves: + OpenSSL names for the most common curves are: <literal>prime256v1</> (NIST P-256), <literal>secp384r1</> (NIST P-384), <literal>secp521r1</> (NIST P-521). - </para> - - <para> The full list of available curves can be shown with the command <command>openssl ecparam -list_curves</command>. Not all of them are usable in <acronym>TLS</> though. @@ -1176,20 +1193,24 @@ include_dir 'conf.d' </varlistentry> <varlistentry id="guc-password-encryption" xreflabel="password_encryption"> - <term><varname>password_encryption</varname> (<type>boolean</type>) + <term><varname>password_encryption</varname> (<type>enum</type>) <indexterm> <primary><varname>password_encryption</> configuration parameter</primary> </indexterm> </term> <listitem> <para> - When a password is specified in <xref - linkend="sql-createuser"> or - <xref linkend="sql-alterrole"> - without writing either <literal>ENCRYPTED</> or - <literal>UNENCRYPTED</>, this parameter determines whether the - password is to be encrypted. The default is <literal>on</> - (encrypt the password). + When a password is specified in <xref linkend="sql-createrole"> or + <xref linkend="sql-alterrole">, this parameter determines the algorithm + to use to encrypt the password. The default value is <literal>md5</>, + which stores the password as an MD5 hash (<literal>on</> is also + accepted, as alias for <literal>md5</>). Setting this parameter to + <literal>scram-sha-256</> will encrypt the password with SCRAM-SHA-256. + </para> + <para> + Note that older clients might lack support for the SCRAM authentication + mechanism, and hence not work with passwords encrypted with + SCRAM-SHA-256. </para> </listitem> </varlistentry> @@ -1240,8 +1261,8 @@ include_dir 'conf.d' </para> <para> - If this is on, you should create users as <literal>username@dbname</>. - When <literal>username</> is passed by a connecting client, + If this is on, you should create users as <replaceable>username@dbname</>. + When <replaceable>username</> is passed by a connecting client, <literal>@</> and the database name are appended to the user name and that database-specific user name is looked up by the server. Note that when you create users with names containing @@ -1311,7 +1332,7 @@ include_dir 'conf.d' If you have a dedicated database server with 1GB or more of RAM, a reasonable starting value for <varname>shared_buffers</varname> is 25% of the memory in your system. There are some workloads where even - large settings for <varname>shared_buffers</varname> are effective, but + larger settings for <varname>shared_buffers</varname> are effective, but because <productname>PostgreSQL</productname> also relies on the operating system cache, it is unlikely that an allocation of more than 40% of RAM to <varname>shared_buffers</varname> will work better than a @@ -1325,11 +1346,6 @@ include_dir 'conf.d' <para> On systems with less than 1GB of RAM, a smaller percentage of RAM is appropriate, so as to leave adequate space for the operating system. - Also, on Windows, large values for <varname>shared_buffers</varname> - aren't as effective. You may find better results keeping the setting - relatively low and using the operating system cache more instead. The - useful range for <varname>shared_buffers</varname> on Windows systems - is generally from 64MB to 512MB. </para> </listitem> @@ -1923,10 +1939,10 @@ include_dir 'conf.d' <xref linkend="guc-shared-buffers">, but smaller than the OS's page cache, where performance might degrade. This setting may have no effect on some platforms. The valid range is between - <literal>0</literal>, which disables controlled writeback, and + <literal>0</literal>, which disables forced writeback, and <literal>2MB</literal>. The default is <literal>512kB</> on Linux, - <literal>0</> elsewhere. (Non-default values of - <symbol>BLCKSZ</symbol> change the default and maximum.) + <literal>0</> elsewhere. (If <symbol>BLCKSZ</symbol> is not 8kB, + the default and maximum values scale proportionally to it.) This parameter can only be set in the <filename>postgresql.conf</> file or on the server command line. </para> @@ -2012,6 +2028,12 @@ include_dir 'conf.d' same or higher value than on the master server. Otherwise, queries will not be allowed in the standby server. </para> + + <para> + When changing this value, consider also adjusting + <xref linkend="guc-max-parallel-workers"> and + <xref linkend="guc-max-parallel-workers-per-gather">. + </para> </listitem> </varlistentry> @@ -2026,8 +2048,9 @@ include_dir 'conf.d' Sets the maximum number of workers that can be started by a single <literal>Gather</literal> node. Parallel workers are taken from the pool of processes established by - <xref linkend="guc-max-worker-processes">. Note that the requested - number of workers may not actually be available at run time. If this + <xref linkend="guc-max-worker-processes">, limited by + <xref linkend="guc-max-parallel-workers">. Note that the requested + number of workers may not actually be available at runtime. If this occurs, the plan will run with fewer workers than expected, which may be inefficient. The default value is 2. Setting this value to 0 disables parallel query execution. @@ -2048,6 +2071,31 @@ include_dir 'conf.d' as much CPU time, memory, I/O bandwidth, and so forth as a query which uses no workers at all. </para> + + <para> + For more information on parallel query, see + <xref linkend="parallel-query">. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-max-parallel-workers" xreflabel="max_parallel_workers"> + <term><varname>max_parallel_workers</varname> (<type>integer</type>) + <indexterm> + <primary><varname>max_parallel_workers</> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the maximum number of workers that the system can support for + parallel queries. The default value is 8. When increasing or + decreasing this value, consider also adjusting + <xref linkend="guc-max-parallel-workers-per-gather">. + Also, note that a setting for this value which is higher than + <xref linkend="guc-max-worker-processes"> will have no effect, + since parallel workers are taken from the pool of worker processes + established by that setting. + </para> </listitem> </varlistentry> @@ -2070,10 +2118,10 @@ include_dir 'conf.d' that are bigger than <xref linkend="guc-shared-buffers">, but smaller than the OS's page cache, where performance might degrade. This setting may have no effect on some platforms. The valid range is - between <literal>0</literal>, which disables controlled writeback, - and <literal>2MB</literal>. The default is <literal>0</> (i.e. no - flush control). (Non-default values of <symbol>BLCKSZ</symbol> - change the maximum.) + between <literal>0</literal>, which disables forced writeback, + and <literal>2MB</literal>. The default is <literal>0</>, i.e., no + forced writeback. (If <symbol>BLCKSZ</symbol> is not 8kB, + the maximum value scales proportionally to it.) </para> </listitem> </varlistentry> @@ -2128,10 +2176,9 @@ include_dir 'conf.d' has materialized a result set, no error will be generated even if the underlying rows in the referenced table have been vacuumed away. Some tables cannot safely be vacuumed early, and so will not be - affected by this setting. Examples include system catalogs and any - table which has a hash index. For such tables this setting will - neither reduce bloat nor create a possibility of a <literal>snapshot - too old</> error on scanning. + affected by this setting, such as system catalogs. For such tables + this setting will neither reduce bloat nor create a possibility + of a <literal>snapshot too old</> error on scanning. </para> </listitem> </varlistentry> @@ -2159,12 +2206,12 @@ include_dir 'conf.d' </term> <listitem> <para> - <varname>wal_level</> determines how much information is written - to the WAL. The default value is <literal>minimal</>, which writes - only the information needed to recover from a crash or immediate - shutdown. <literal>replica</> adds logging required for WAL - archiving as well as information required to run - read-only queries on a standby server. Finally, + <varname>wal_level</> determines how much information is written to + the WAL. The default value is <literal>replica</>, which writes enough + data to support WAL archiving and replication, including running + read-only queries on a standby server. <literal>minimal</> removes all + logging except the information required to recover from a crash or + immediate shutdown. Finally, <literal>logical</> adds information necessary to support logical decoding. Each level includes the information logged at all lower levels. This parameter can only be set at server start. @@ -2533,10 +2580,11 @@ include_dir 'conf.d' <para> Specifies how often the WAL writer flushes WAL. After flushing WAL it sleeps for <varname>wal_writer_delay</> milliseconds, unless woken up - by an asynchronously committing transaction. In case the last flush + by an asynchronously committing transaction. If the last flush happened less than <varname>wal_writer_delay</> milliseconds ago and less than <varname>wal_writer_flush_after</> bytes of WAL have been - produced since, WAL is only written to the OS, not flushed to disk. + produced since, then WAL is only written to the operating system, not + flushed to disk. The default value is 200 milliseconds (<literal>200ms</>). Note that on many systems, the effective resolution of sleep delays is 10 milliseconds; setting <varname>wal_writer_delay</> to a value that is @@ -2555,12 +2603,12 @@ include_dir 'conf.d' </term> <listitem> <para> - Specifies how often the WAL writer flushes WAL. In case the last flush + Specifies how often the WAL writer flushes WAL. If the last flush happened less than <varname>wal_writer_delay</> milliseconds ago and less than <varname>wal_writer_flush_after</> bytes of WAL have been - produced since, WAL is only written to the OS, not flushed to disk. - If <varname>wal_writer_flush_after</> is set to <literal>0</> WAL is - flushed every time the WAL writer has written WAL. The default is + produced since, then WAL is only written to the operating system, not + flushed to disk. If <varname>wal_writer_flush_after</> is set + to <literal>0</> then WAL data is flushed immediately. The default is <literal>1MB</literal>. This parameter can only be set in the <filename>postgresql.conf</> file or on the server command line. </para> @@ -2635,7 +2683,7 @@ include_dir 'conf.d' <listitem> <para> Maximum time between automatic WAL checkpoints, in seconds. - The valid range is between 30 seconds and one hour. + The valid range is between 30 seconds and one day. The default is five minutes (<literal>5min</>). Increasing this parameter can increase the amount of time needed for crash recovery. @@ -2680,10 +2728,10 @@ include_dir 'conf.d' that are bigger than <xref linkend="guc-shared-buffers">, but smaller than the OS's page cache, where performance might degrade. This setting may have no effect on some platforms. The valid range is - between <literal>0</literal>, which disables controlled writeback, + between <literal>0</literal>, which disables forced writeback, and <literal>2MB</literal>. The default is <literal>256kB</> on - Linux, <literal>0</> elsewhere. (Non-default values of - <symbol>BLCKSZ</symbol> change the default and maximum.) + Linux, <literal>0</> elsewhere. (If <symbol>BLCKSZ</symbol> is not + 8kB, the default and maximum values scale proportionally to it.) This parameter can only be set in the <filename>postgresql.conf</> file or on the server command line. </para> @@ -2841,12 +2889,10 @@ include_dir 'conf.d' parameter is greater than zero, the server will switch to a new segment file whenever this many seconds have elapsed since the last segment file switch, and there has been any database activity, - including a single checkpoint. (Increasing - <varname>checkpoint_timeout</> will reduce unnecessary - checkpoints on an idle system.) - Note that archived files that are closed early - due to a forced switch are still the same length as completely full - files. Therefore, it is unwise to use a very short + including a single checkpoint (checkpoints are skipped if there is + no database activity). Note that archived files that are closed + early due to a forced switch are still the same length as completely + full files. Therefore, it is unwise to use a very short <varname>archive_timeout</> — it will bloat your archive storage. <varname>archive_timeout</> settings of a minute or so are usually reasonable. You should consider using streaming replication, @@ -2908,7 +2954,7 @@ include_dir 'conf.d' Specifies the maximum number of concurrent connections from standby servers or streaming base backup clients (i.e., the maximum number of simultaneously running WAL sender - processes). The default is zero, meaning replication is + processes). The default is 10. The value 0 means replication is disabled. WAL sender processes count towards the total number of connections, so the parameter cannot be set higher than <xref linkend="guc-max-connections">. Abrupt streaming client @@ -2933,7 +2979,7 @@ include_dir 'conf.d' <para> Specifies the maximum number of replication slots (see <xref linkend="streaming-replication-slots">) that the server - can support. The default is zero. This parameter can only be set at + can support. The default is 10. This parameter can only be set at server start. <varname>wal_level</varname> must be set to <literal>replica</literal> or higher to allow replication slots to @@ -2952,7 +2998,7 @@ include_dir 'conf.d' <listitem> <para> Specifies the minimum number of past log file segments kept in the - <filename>pg_xlog</> + <filename>pg_wal</> directory, in case a standby server needs to fetch them for streaming replication. Each segment is normally 16 megabytes. If a standby server connected to the sending server falls behind by more than @@ -2966,7 +3012,7 @@ include_dir 'conf.d' <para> This sets only the minimum number of segments retained in - <filename>pg_xlog</>; the system might need to retain more segments + <filename>pg_wal</>; the system might need to retain more segments for WAL archival or to recover from a checkpoint. If <varname>wal_keep_segments</> is zero (the default), the system doesn't keep any extra segments for standby purposes, so the number @@ -2999,7 +3045,7 @@ include_dir 'conf.d' </varlistentry> <varlistentry id="guc-track-commit-timestamp" xreflabel="track_commit_timestamp"> - <term><varname>track_commit_timestamp</varname> (<type>bool</type>) + <term><varname>track_commit_timestamp</varname> (<type>boolean</type>) <indexterm> <primary><varname>track_commit_timestamp</> configuration parameter</primary> </indexterm> @@ -3048,41 +3094,71 @@ include_dir 'conf.d' transactions waiting for commit will be allowed to proceed after these standby servers confirm receipt of their data. The synchronous standbys will be those whose names appear - earlier in this list, and + in this list, and that are both currently connected and streaming data in real-time (as shown by a state of <literal>streaming</literal> in the <link linkend="monitoring-stats-views-table"> <literal>pg_stat_replication</></link> view). - Other standby servers appearing later in this list represent potential - synchronous standbys. If any of the current synchronous - standbys disconnects for whatever reason, - it will be replaced immediately with the next-highest-priority standby. - Specifying more than one standby name can allow very high availability. + Specifying more than one standby names can allow very high availability. </para> <para> This parameter specifies a list of standby servers using either of the following syntaxes: <synopsis> -<replaceable class="parameter">num_sync</replaceable> ( <replaceable class="parameter">standby_name</replaceable> [, ...] ) +[FIRST] <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="parameter">standby_name</replaceable> [, ...] ) +ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="parameter">standby_name</replaceable> [, ...] ) <replaceable class="parameter">standby_name</replaceable> [, ...] </synopsis> where <replaceable class="parameter">num_sync</replaceable> is the number of synchronous standbys that transactions need to wait for replies from, and <replaceable class="parameter">standby_name</replaceable> - is the name of a standby server. For example, a setting of - <literal>3 (s1, s2, s3, s4)</> makes transaction commits wait - until their WAL records are received by three higher-priority standbys - chosen from standby servers <literal>s1</>, <literal>s2</>, - <literal>s3</> and <literal>s4</>. - </para> - <para> - The second syntax was used before <productname>PostgreSQL</> + is the name of a standby server. + <literal>FIRST</> and <literal>ANY</> specify the method to choose + synchronous standbys from the listed servers. + </para> + <para> + The keyword <literal>FIRST</>, coupled with + <replaceable class="parameter">num_sync</replaceable>, specifies a + priority-based synchronous replication and makes transaction commits + wait until their WAL records are replicated to + <replaceable class="parameter">num_sync</replaceable> synchronous + standbys chosen based on their priorities. For example, a setting of + <literal>FIRST 3 (s1, s2, s3, s4)</> will cause each commit to wait for + replies from three higher-priority standbys chosen from standby servers + <literal>s1</>, <literal>s2</>, <literal>s3</> and <literal>s4</>. + The standbys whose names appear earlier in the list are given higher + priority and will be considered as synchronous. Other standby servers + appearing later in this list represent potential synchronous standbys. + If any of the current synchronous standbys disconnects for whatever + reason, it will be replaced immediately with the next-highest-priority + standby. The keyword <literal>FIRST</> is optional. + </para> + <para> + The keyword <literal>ANY</>, coupled with + <replaceable class="parameter">num_sync</replaceable>, specifies a + quorum-based synchronous replication and makes transaction commits + wait until their WAL records are replicated to <emphasis>at least</> + <replaceable class="parameter">num_sync</replaceable> listed standbys. + For example, a setting of <literal>ANY 3 (s1, s2, s3, s4)</> will cause + each commit to proceed as soon as at least any three standbys of + <literal>s1</>, <literal>s2</>, <literal>s3</> and <literal>s4</> + reply. + </para> + <para> + <literal>FIRST</> and <literal>ANY</> are case-insensitive. If these + keywords are used as the name of a standby server, + its <replaceable class="parameter">standby_name</replaceable> must + be double-quoted. + </para> + <para> + The third syntax was used before <productname>PostgreSQL</> version 9.6 and is still supported. It's the same as the first syntax - with <replaceable class="parameter">num_sync</replaceable> equal to 1. - For example, <literal>1 (s1, s2)</> and - <literal>s1, s2</> have the same meaning: either <literal>s1</> - or <literal>s2</> is chosen as a synchronous standby. + with <literal>FIRST</> and + <replaceable class="parameter">num_sync</replaceable> equal to 1. + For example, <literal>FIRST 1 (s1, s2)</> and <literal>s1, s2</> have + the same meaning: either <literal>s1</> or <literal>s2</> is chosen + as a synchronous standby. </para> <para> The name of a standby server for this purpose is the @@ -3179,7 +3255,7 @@ include_dir 'conf.d' <para> Specifies whether or not you can connect and run queries during recovery, as described in <xref linkend="hot-standby">. - The default value is <literal>off</literal>. + The default value is <literal>on</literal>. This parameter can only be set at server start. It only has effect during archive recovery or in standby mode. </para> @@ -3262,7 +3338,7 @@ include_dir 'conf.d' to the primary or upstream standby, where it can be seen using the <link linkend="monitoring-stats-views-table"> <literal>pg_stat_replication</></link> view. The standby will report - the last transaction log position it has written, the last position it + the last write-ahead log location it has written, the last position it has flushed to disk, and the last position it has applied. This parameter's value is the maximum interval, in seconds, between reports. Updates are @@ -3342,7 +3418,7 @@ include_dir 'conf.d' <para> Specify how long the standby server should wait when WAL data is not available from any sources (streaming replication, - local <filename>pg_xlog</> or WAL archive) before retrying to + local <filename>pg_wal</> or WAL archive) before retrying to retrieve WAL data. This parameter can only be set in the <filename>postgresql.conf</> file or on the server command line. The default value is 5 seconds. Units are milliseconds if not specified. @@ -3363,6 +3439,72 @@ include_dir 'conf.d' </variablelist> </sect2> + + <sect2 id="runtime-config-replication-subscriber"> + <title>Subscribers</title> + + <para> + These settings control the behavior of a logical replication subscriber. + Their values on the publisher are irrelevant. + </para> + + <para> + Note that <varname>wal_receiver_timeout</varname> and + <varname>wal_retrieve_retry_interval</varname> configuration parameters + affect the logical replication workers as well. + </para> + + <variablelist> + + <varlistentry id="guc-max-logical-replication-workers" xreflabel="max_logical_replication_workers"> + <term><varname>max_logical_replication_workers</varname> (<type>int</type>) + <indexterm> + <primary><varname>max_logical_replication_workers</> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Specifies maximum number of logical replication workers. This includes + both apply workers and table synchronization workers. + </para> + <para> + Logical replication workers are taken from the pool defined by + <varname>max_worker_processes</varname>. + </para> + <para> + The default value is 4. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-max-sync-workers-per-subscription" xreflabel="max_sync_workers_per_subscription"> + <term><varname>max_sync_workers_per_subscription</varname> (<type>integer</type>) + <indexterm> + <primary><varname>max_sync_workers_per_subscription</> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Maximum number of synchronization workers per subscription. This + parameter controls the amount of paralelism of the initial data copy + during the subscription initialization or when new tables are added. + </para> + <para> + Currently, there can be only one synchronization worker per table. + </para> + <para> + The synchronization workers are taken from the pool defined by + <varname>max_logical_replication_workers</varname>. + </para> + <para> + The default value is 2. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect2> + </sect1> <sect1 id="runtime-config-query"> @@ -3407,6 +3549,20 @@ include_dir 'conf.d' </listitem> </varlistentry> + <varlistentry id="guc-enable-gathermerge" xreflabel="enable_gathermerge"> + <term><varname>enable_gathermerge</varname> (<type>boolean</type>) + <indexterm> + <primary><varname>enable_gathermerge</> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Enables or disables the query planner's use of gather + merge plan types. The default is <literal>on</>. + </para> + </listitem> + </varlistentry> + <varlistentry id="guc-enable-hashagg" xreflabel="enable_hashagg"> <term><varname>enable_hashagg</varname> (<type>boolean</type>) <indexterm> @@ -3746,16 +3902,37 @@ include_dir 'conf.d' </listitem> </varlistentry> - <varlistentry id="guc-min-parallel-relation-size" xreflabel="min_parallel_relation_size"> - <term><varname>min_parallel_relation_size</varname> (<type>integer</type>) + <varlistentry id="guc-min-parallel-table-scan-size" xreflabel="min_parallel_table_scan_size"> + <term><varname>min_parallel_table_scan_size</varname> (<type>integer</type>) + <indexterm> + <primary><varname>min_parallel_table_scan_size</> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + Sets the minimum amount of table data that must be scanned in order + for a parallel scan to be considered. For a parallel sequential scan, + the amount of table data scanned is always equal to the size of the + table, but when indexes are used the amount of table data + scanned will normally be less. The default is 8 + megabytes (<literal>8MB</>). + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-min-parallel-index-scan-size" xreflabel="min_parallel_index_scan_size"> + <term><varname>min_parallel_index_scan_size</varname> (<type>integer</type>) <indexterm> - <primary><varname>min_parallel_relation_size</> configuration parameter</primary> + <primary><varname>min_parallel_index_scan_size</> configuration parameter</primary> </indexterm> </term> <listitem> <para> - Sets the minimum size of relations to be considered for parallel scan. - The default is 8 megabytes (<literal>8MB</>). + Sets the minimum amount of index data that must be scanned in order + for a parallel scan to be considered. Note that a parallel index scan + typically won't touch the entire index; it is the number of pages + which the planner believes will actually be touched by the scan which + is relevant. The default is 512 kilobytes (<literal>512kB</>). </para> </listitem> </varlistentry> @@ -4170,6 +4347,11 @@ SELECT * FROM parent WHERE key = 2400; <primary>where to log</primary> </indexterm> + <indexterm> + <primary>current_logfiles</primary> + <secondary>and the log_destination configuration parameter</secondary> + </indexterm> + <variablelist> <varlistentry id="guc-log-destination" xreflabel="log_destination"> @@ -4200,6 +4382,27 @@ SELECT * FROM parent WHERE key = 2400; <xref linkend="guc-logging-collector"> must be enabled to generate CSV-format log output. </para> + <para> + When either <systemitem>stderr</systemitem> or + <systemitem>csvlog</systemitem> are included, the file + <filename>current_logfiles</> is created to record the location + of the log file(s) currently in use by the logging collector and the + associated logging destination. This provides a convenient way to + find the logs currently in use by the instance. Here is an example of + this file's content: +<programlisting> +stderr log/postgresql.log +csvlog log/postgresql.csv +</programlisting> + + <filename>current_logfiles</filename> is recreated when a new log file + is created as an effect of rotation, and + when <varname>log_destination</> is reloaded. It is removed when + neither <systemitem>stderr</systemitem> + nor <systemitem>csvlog</systemitem> are included + in <varname>log_destination</>, and when the logging collector is + disabled. + </para> <note> <para> @@ -4291,7 +4494,7 @@ local0.* /var/log/postgresql cluster data directory. This parameter can only be set in the <filename>postgresql.conf</> file or on the server command line. - The default is <literal>pg_log</literal>. + The default is <literal>log</literal>. </para> </listitem> </varlistentry> @@ -5024,7 +5227,8 @@ local0.* /var/log/postgresql value will pad on the left. Padding can be useful to aid human readability in log files. This parameter can only be set in the <filename>postgresql.conf</> - file or on the server command line. The default is an empty string. + file or on the server command line. The default is + <literal>'%m [%p] '</> which logs a time stamp and the process ID. <informaltable> <tgroup cols="3"> @@ -5162,6 +5366,17 @@ FROM pg_stat_activity; include those escapes if you are logging to <application>syslog</>. </para> </tip> + + <tip> + <para> + The <literal>%q</> escape is useful when including information that is + only available in session (backend) context like user or database + name. For example: +<programlisting> +log_line_prefix = '%m [%p] %q%u@%d/%a ' +</programlisting> + </para> + </tip> </listitem> </varlistentry> @@ -5414,9 +5629,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; <title>Process Title</title> <para> - These settings control how the process title as seen - by <command>ps</command> is modified. See <xref linkend="monitoring-ps"> - for details. + These settings control how process titles of server processes are + modified. Process titles are typically viewed using programs like + <application>ps</> or, on Windows, <application>Process Explorer</>. + See <xref linkend="monitoring-ps"> for details. </para> <variablelist> @@ -5429,18 +5645,14 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; <listitem> <para> Sets the cluster name that appears in the process title for all - processes in this cluster. The name can be any string of less than - <symbol>NAMEDATALEN</> characters (64 characters in a standard + server processes in this cluster. The name can be any string of less + than <symbol>NAMEDATALEN</> characters (64 characters in a standard build). Only printable ASCII characters may be used in the <varname>cluster_name</varname> value. Other characters will be replaced with question marks (<literal>?</literal>). No name is shown if this parameter is set to the empty string <literal>''</> (which is the default). This parameter can only be set at server start. </para> - <para> - The process title is typically viewed using programs like - <application>ps</> or, on Windows, <application>Process Explorer</>. - </para> </listitem> </varlistentry> @@ -5453,9 +5665,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; <listitem> <para> Enables updating of the process title every time a new SQL command - is received by the server. The process title is typically viewed - by the <command>ps</> command, - or in Windows by using the <application>Process Explorer</>. + is received by the server. + This setting defaults to <literal>on</> on most platforms, but it + defaults to <literal>off</> on Windows due to that platform's larger + overhead for updating the process title. Only superusers can change this setting. </para> </listitem> @@ -5844,7 +6057,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; <para> Vacuum also allows removal of old files from the - <filename>pg_clog</> subdirectory, which is why the default + <filename>pg_xact</> subdirectory, which is why the default is a relatively low 200 million transactions. This parameter can only be set at server start, but the setting can be reduced for individual tables by @@ -7169,7 +7382,43 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' tables in a single serializable transaction. This parameter can only be set at server start. </para> + </listitem> + </varlistentry> + <varlistentry id="guc-max-pred-locks-per-relation" xreflabel="max_pred_locks_per_relation"> + <term><varname>max_pred_locks_per_relation</varname> (<type>integer</type>) + <indexterm> + <primary><varname>max_pred_locks_per_relation</> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This controls how many pages or tuples of a single relation can be + predicate-locked before the lock is promoted to covering the whole + relation. Values greater than or equal to zero mean an absolute + limit, while negative values + mean <xref linkend="guc-max-pred-locks-per-transaction"> divided by + the absolute value of this setting. The default is -2, which keeps + the behaviour from previous versions of <productname>PostgreSQL</>. + This parameter can only be set in the <filename>postgresql.conf</> + file or on the server command line. + </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-max-pred-locks-per-page" xreflabel="max_pred_locks_per_page"> + <term><varname>max_pred_locks_per_page</varname> (<type>integer</type>) + <indexterm> + <primary><varname>max_pred_locks_per_page</> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This controls how many rows on a single page can be predicate-locked + before the lock is promoted to covering the whole page. The default + is 2. This parameter can only be set in + the <filename>postgresql.conf</> file or on the server command line. + </para> </listitem> </varlistentry> @@ -7367,36 +7616,6 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' </listitem> </varlistentry> - <varlistentry id="guc-sql-inheritance" xreflabel="sql_inheritance"> - <term><varname>sql_inheritance</varname> (<type>boolean</type>) - <indexterm> - <primary><varname>sql_inheritance</> configuration parameter</primary> - </indexterm> - <indexterm><primary>inheritance</></> - </term> - <listitem> - <para> - This setting controls whether undecorated table references are - considered to include inheritance child tables. The default is - <literal>on</>, which means child tables are included (thus, - a <literal>*</> suffix is assumed by default). If turned - <literal>off</>, child tables are not included (thus, an - <literal>ONLY</literal> prefix is assumed). The SQL standard - requires child tables to be included, so the <literal>off</> setting - is not spec-compliant, but it is provided for compatibility with - <productname>PostgreSQL</> releases prior to 7.1. - See <xref linkend="ddl-inherit"> for more information. - </para> - - <para> - Turning <varname>sql_inheritance</> off is deprecated, because that - behavior has been found to be error-prone as well as contrary to SQL - standard. Discussions of inheritance behavior elsewhere in this - manual generally assume that it is <literal>on</>. - </para> - </listitem> - </varlistentry> - <varlistentry id="guc-standard-conforming-strings" xreflabel="standard_conforming_strings"> <term><varname>standard_conforming_strings</varname> (<type>boolean</type>) <indexterm><primary>strings</><secondary>standard conforming</></> @@ -7622,11 +7841,9 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' </term> <listitem> <para> - Reports whether <productname>PostgreSQL</> was built with - support for 64-bit-integer dates and times. This can be - disabled by configuring with <literal>--disable-integer-datetimes</> - when building <productname>PostgreSQL</>. The default value is - <literal>on</literal>. + Reports whether <productname>PostgreSQL</> was built with support for + 64-bit-integer dates and times. As of <productname>PostgreSQL</> 10, + this is always <literal>on</literal>. </para> </listitem> </varlistentry> @@ -8137,6 +8354,38 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) </listitem> </varlistentry> + <varlistentry id="guc-wal-consistency-checking" xreflabel="wal_consistency_checking"> + <term><varname>wal_consistency_checking</varname> (<type>string</type>) + <indexterm> + <primary><varname>wal_consistency_checking</> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter is intended to be used to check for bugs in the WAL + redo routines. When enabled, full-page images of any buffers modified + in conjunction with the WAL record are added to the record. + If the record is subsequently replayed, the system will first apply + each record and then test whether the buffers modified by the record + match the stored images. In certain cases (such as hint bits), minor + variations are acceptable, and will be ignored. Any unexpected + differences will result in a fatal error, terminating recovery. + </para> + + <para> + The default value of this setting is the empty string, which disables + the feature. It can be set to <literal>all</literal> to check all + records, or to a comma-separated list of resource managers to check + only records originating from those resource managers. Currently, + the supported resource managers are <literal>heap</>, + <literal>heap2</>, <literal>btree</>, <literal>hash</>, + <literal>gin</>, <literal>gist</>, <literal>sequence</>, + <literal>spgist</>, <literal>brin</>, and <literal>generic</>. Only + superusers can change this setting. + </para> + </listitem> + </varlistentry> + <varlistentry id="guc-wal-debug" xreflabel="wal_debug"> <term><varname>wal_debug</varname> (<type>boolean</type>) <indexterm> diff --git a/doc/src/sgml/contacts.sgml b/doc/src/sgml/contacts.sgml index a981625027..308eb418a5 100644 --- a/doc/src/sgml/contacts.sgml +++ b/doc/src/sgml/contacts.sgml @@ -16,7 +16,7 @@ and the mailing lists themselves. <para> Refer to the introduction in this manual or to the <productname>PostgreSQL</productname> -<ulink url="http://www.postgresql.org">web page</ulink> +<ulink url="https://www.postgresql.org">web page</ulink> for subscription information to the no-cost mailing lists. </para> diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml index fdc7a07534..16458ec68d 100644 --- a/doc/src/sgml/contrib.sgml +++ b/doc/src/sgml/contrib.sgml @@ -103,6 +103,7 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged; </para> &adminpack; + &amcheck; &auth-delay; &auto-explain; &bloom; @@ -146,7 +147,6 @@ CREATE EXTENSION <replaceable>module_name</> FROM unpackaged; &tablefunc; &tcn; &test-decoding; - &tsearch2; &tsm-system-rows; &tsm-system-time; &unaccent; diff --git a/doc/src/sgml/custom-scan.sgml b/doc/src/sgml/custom-scan.sgml index 1ca9247124..6159c3a24e 100644 --- a/doc/src/sgml/custom-scan.sgml +++ b/doc/src/sgml/custom-scan.sgml @@ -340,6 +340,19 @@ void (*InitializeWorkerCustomScan) (CustomScanState *node, <para> <programlisting> +void (*ShutdownCustomScan) (CustomScanState *node); +</programlisting> + Release resources when it is anticipated the node will not be executed + to completion. This is not called in all cases; sometimes, + <literal>EndCustomScan</> may be called without this function having + been called first. Since the DSM segment used by parallel query is + destroyed just after this callback is invoked, custom scan providers that + wish to take some action before the DSM segment goes away should implement + this method. + </para> + + <para> +<programlisting> void (*ExplainCustomScan) (CustomScanState *node, List *ancestors, ExplainState *es); diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 1da27cdd3d..0ea06782b1 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -167,6 +167,12 @@ </row> <row> + <entry><type>macaddr8</type></entry> + <entry></entry> + <entry>MAC (Media Access Control) address (EUI-64 format)</entry> + </row> + + <row> <entry><type>money</type></entry> <entry></entry> <entry>currency amount</entry> @@ -750,7 +756,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; floating-point arithmetic does not follow IEEE 754, these values will probably not work as expected.) When writing these values as constants in an SQL command, you must put quotes around them, - for example <literal>UPDATE table SET x = 'Infinity'</>. On input, + for example <literal>UPDATE table SET x = '-Infinity'</>. On input, these strings are recognized in a case-insensitive manner. </para> @@ -937,7 +943,7 @@ ALTER SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceab </thead> <tbody> <row> - <entry>money</entry> + <entry><type>money</type></entry> <entry>8 bytes</entry> <entry>currency amount</entry> <entry>-92233720368547758.08 to +92233720368547758.07</entry> @@ -977,6 +983,11 @@ SELECT '52093.89'::money::numeric::float8; </para> <para> + Division of a <type>money</type> value by an integer value is performed + with truncation of the fractional part towards zero. To get a rounded + result, divide by a floating-point value, or cast the <type>money</type> + value to <type>numeric</> before dividing and back to <type>money</type> + afterwards. (The latter is preferable to avoid risking precision loss.) When a <type>money</type> value is divided by another <type>money</type> value, the result is <type>double precision</type> (i.e., a pure number, not money); the currency units cancel each other out in the division. @@ -1580,7 +1591,7 @@ SELECT E'\\xDEADBEEF'; <entry>both date and time (no time zone)</entry> <entry>4713 BC</entry> <entry>294276 AD</entry> - <entry>1 microsecond / 14 digits</entry> + <entry>1 microsecond</entry> </row> <row> <entry><type>timestamp [ (<replaceable>p</replaceable>) ] with time zone</type></entry> @@ -1588,7 +1599,7 @@ SELECT E'\\xDEADBEEF'; <entry>both date and time, with time zone</entry> <entry>4713 BC</entry> <entry>294276 AD</entry> - <entry>1 microsecond / 14 digits</entry> + <entry>1 microsecond</entry> </row> <row> <entry><type>date</type></entry> @@ -1604,15 +1615,15 @@ SELECT E'\\xDEADBEEF'; <entry>time of day (no date)</entry> <entry>00:00:00</entry> <entry>24:00:00</entry> - <entry>1 microsecond / 14 digits</entry> + <entry>1 microsecond</entry> </row> <row> <entry><type>time [ (<replaceable>p</replaceable>) ] with time zone</type></entry> <entry>12 bytes</entry> - <entry>times of day only, with time zone</entry> + <entry>time of day (no date), with time zone</entry> <entry>00:00:00+1459</entry> <entry>24:00:00-1459</entry> - <entry>1 microsecond / 14 digits</entry> + <entry>1 microsecond</entry> </row> <row> <entry><type>interval [ <replaceable>fields</replaceable> ] [ (<replaceable>p</replaceable>) ]</type></entry> @@ -1620,7 +1631,7 @@ SELECT E'\\xDEADBEEF'; <entry>time interval</entry> <entry>-178000000 years</entry> <entry>178000000 years</entry> - <entry>1 microsecond / 14 digits</entry> + <entry>1 microsecond</entry> </row> </tbody> </tgroup> @@ -1643,40 +1654,7 @@ SELECT E'\\xDEADBEEF'; <replaceable>p</replaceable> which specifies the number of fractional digits retained in the seconds field. By default, there is no explicit bound on precision. The allowed range of - <replaceable>p</replaceable> is from 0 to 6 for the - <type>timestamp</type> and <type>interval</type> types. - </para> - - <note> - <para> - When <type>timestamp</> values are stored as eight-byte integers - (currently the default), microsecond precision is available over - the full range of values. When <type>timestamp</> values are - stored as double precision floating-point numbers instead (a - deprecated compile-time option), the effective limit of precision - might be less than 6. <type>timestamp</type> values are stored as - seconds before or after midnight 2000-01-01. When - <type>timestamp</type> values are implemented using floating-point - numbers, microsecond precision is achieved for dates within a few - years of 2000-01-01, but the precision degrades for dates further - away. Note that using floating-point datetimes allows a larger - range of <type>timestamp</type> values to be represented than - shown above: from 4713 BC up to 5874897 AD. - </para> - - <para> - The same compile-time option also determines whether - <type>time</type> and <type>interval</type> values are stored as - floating-point numbers or eight-byte integers. In the - floating-point case, large <type>interval</type> values degrade in - precision as the size of the interval increases. - </para> - </note> - - <para> - For the <type>time</type> types, the allowed range of - <replaceable>p</replaceable> is from 0 to 6 when eight-byte integer - storage is used, or from 0 to 10 when floating-point storage is used. + <replaceable>p</replaceable> is from 0 to 6. </para> <para> @@ -1759,9 +1737,10 @@ MINUTE TO SECOND specification giving the number of fractional digits in the seconds field. Precision can be specified for <type>time</type>, <type>timestamp</type>, and - <type>interval</type> types. The allowed values are mentioned - above. If no precision is specified in a constant specification, - it defaults to the precision of the literal value. + <type>interval</type> types, and can range from 0 to 6. + If no precision is specified in a constant specification, + it defaults to the precision of the literal value (but not + more than 6 digits). </para> <sect3> @@ -3460,6 +3439,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays <entry>MAC addresses</entry> </row> + <row> + <entry><type>macaddr8</type></entry> + <entry>8 bytes</entry> + <entry>MAC addresses (EUI-64 format)</entry> + </row> + </tbody> </tgroup> </table> @@ -3700,6 +3685,77 @@ SELECT person.name, holidays.num_weeks FROM person, holidays </para> </sect2> + <sect2 id="datatype-macaddr8"> + <title><type>macaddr8</type></title> + + <indexterm> + <primary>macaddr8 (data type)</primary> + </indexterm> + + <indexterm> + <primary>MAC address (EUI-64 format)</primary> + <see>macaddr</see> + </indexterm> + + <para> + The <type>macaddr8</> type stores MAC addresses in EUI-64 + format, known for example from Ethernet card hardware addresses + (although MAC addresses are used for other purposes as well). + This type can accept both 6 and 8 byte length MAC addresses + and stores them in 8 byte length format. MAC addresses given + in 6 byte format will be stored in 8 byte length format with the + 4th and 5th bytes set to FF and FE, respectively. + + Note that IPv6 uses a modified EUI-64 format where the 7th bit + should be set to one after the conversion from EUI-48. The + function <function>macaddr8_set7bit</> is provided to make this + change. + + Generally speaking, any input which is comprised of pairs of hex + digits (on byte boundaries), optionally separated consistently by + one of <literal>':'</>, <literal>'-'</> or <literal>'.'</>, is + accepted. The number of hex digits must be either 16 (8 bytes) or + 12 (6 bytes). Leading and trailing whitespace is ignored. + + The following are examples of input formats that are accepted: + + <simplelist> + <member><literal>'08:00:2b:01:02:03:04:05'</></member> + <member><literal>'08-00-2b-01-02-03-04-05'</></member> + <member><literal>'08002b:0102030405'</></member> + <member><literal>'08002b-0102030405'</></member> + <member><literal>'0800.2b01.0203.0405'</></member> + <member><literal>'0800-2b01-0203-0405'</></member> + <member><literal>'08002b01:02030405'</></member> + <member><literal>'08002b0102030405'</></member> + </simplelist> + + These examples would all specify the same address. Upper and + lower case is accepted for the digits + <literal>a</> through <literal>f</>. Output is always in the + first of the forms shown. + + The last six input formats that are mentioned above are not part + of any standard. + + To convert a traditional 48 bit MAC address in EUI-48 format to + modified EUI-64 format to be included as the host portion of an + IPv6 address, use <function>macaddr8_set7bit</> as shown: + +<programlisting> +SELECT macaddr8_set7bit('08:00:2b:01:02:03'); +<computeroutput> + macaddr8_set7bit +------------------------- + 0a:00:2b:ff:fe:01:02:03 +(1 row) +</computeroutput> +</programlisting> + + </para> + + </sect2> + </sect1> <sect1 id="datatype-bit"> @@ -3959,15 +4015,7 @@ SELECT 'fat & rat & ! cat'::tsquery; tsquery ------------------------ 'fat' & 'rat' & !'cat' - -SELECT '(fat | rat) <-> cat'::tsquery; - tsquery ------------------------------------ - 'fat' <-> 'cat' | 'rat' <-> 'cat' </programlisting> - - The last example demonstrates that <type>tsquery</type> sometimes - rearranges nested operators into a logically equivalent formulation. </para> <para> @@ -4584,7 +4632,7 @@ SELECT * FROM pg_attribute <para> The <type>pg_lsn</type> data type can be used to store LSN (Log Sequence - Number) data which is a pointer to a location in the XLOG. This type is a + Number) data which is a pointer to a location in the WAL. This type is a representation of <type>XLogRecPtr</type> and an internal system type of <productname>PostgreSQL</productname>. </para> @@ -4597,7 +4645,7 @@ SELECT * FROM pg_attribute standard comparison operators, like <literal>=</literal> and <literal>></literal>. Two LSNs can be subtracted using the <literal>-</literal> operator; the result is the number of bytes separating - those write-ahead log positions. + those write-ahead log locations. </para> </sect1> @@ -4673,6 +4721,10 @@ SELECT * FROM pg_attribute </indexterm> <indexterm zone="datatype-pseudo"> + <primary>unknown</primary> + </indexterm> + + <indexterm zone="datatype-pseudo"> <primary>opaque</primary> </indexterm> @@ -4794,8 +4846,15 @@ SELECT * FROM pg_attribute </row> <row> + <entry><type>unknown</></entry> + <entry>Identifies a not-yet-resolved type, e.g. of an undecorated + string literal.</entry> + </row> + + <row> <entry><type>opaque</></entry> - <entry>An obsolete type name that formerly served all the above purposes.</entry> + <entry>An obsolete type name that formerly served many of the above + purposes.</entry> </row> </tbody> </tgroup> diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml index ffd0715128..ef9139f9e3 100644 --- a/doc/src/sgml/datetime.sgml +++ b/doc/src/sgml/datetime.sgml @@ -384,20 +384,39 @@ <para> A <replaceable>zone_abbreviation</replaceable> is just the abbreviation - being defined. The <replaceable>offset</replaceable> is the equivalent - offset in seconds from UTC, positive being east from Greenwich and - negative being west. For example, -18000 would be five hours west - of Greenwich, or North American east coast standard time. <literal>D</> - indicates that the zone name represents local daylight-savings time rather - than standard time. Alternatively, a <replaceable>time_zone_name</> can - be given, in which case that time zone definition is consulted, and the - abbreviation's meaning in that zone is used. This alternative is - recommended only for abbreviations whose meaning has historically varied, - as looking up the meaning is noticeably more expensive than just using - a fixed integer value. + being defined. An <replaceable>offset</replaceable> is an integer giving + the equivalent offset in seconds from UTC, positive being east from + Greenwich and negative being west. For example, -18000 would be five + hours west of Greenwich, or North American east coast standard time. + <literal>D</> indicates that the zone name represents local + daylight-savings time rather than standard time. </para> <para> + Alternatively, a <replaceable>time_zone_name</> can be given, referencing + a zone name defined in the IANA timezone database. The zone's definition + is consulted to see whether the abbreviation is or has been in use in + that zone, and if so, the appropriate meaning is used — that is, + the meaning that was currently in use at the timestamp whose value is + being determined, or the meaning in use immediately before that if it + wasn't current at that time, or the oldest meaning if it was used only + after that time. This behavior is essential for dealing with + abbreviations whose meaning has historically varied. It is also allowed + to define an abbreviation in terms of a zone name in which that + abbreviation does not appear; then using the abbreviation is just + equivalent to writing out the zone name. + </para> + + <tip> + <para> + Using a simple integer <replaceable>offset</replaceable> is preferred + when defining an abbreviation whose offset from UTC has never changed, + as such abbreviations are much cheaper to process than those that + require consulting a time zone definition. + </para> + </tip> + + <para> The <literal>@INCLUDE</> syntax allows inclusion of another file in the <filename>.../share/timezonesets/</> directory. Inclusion can be nested, to a limited depth. diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml index f784171983..71339bf81d 100755 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -12,7 +12,8 @@ Subsequently, we discuss how tables can be organized into schemas, and how privileges can be assigned to tables. Finally, we will briefly look at other features that affect the data storage, - such as inheritance, views, functions, and triggers. + such as inheritance, table partitioning, views, functions, and + triggers. </para> <sect1 id="ddl-basics"> @@ -1869,9 +1870,11 @@ REVOKE ALL ON accounts FROM PUBLIC; <para> When multiple policies apply to a given query, they are combined using - <literal>OR</literal>, so that a row is accessible if any policy allows - it. This is similar to the rule that a given role has the privileges - of all roles that they are a member of. + either <literal>OR</literal> (for permissive policies, which are the + default) or using <literal>AND</literal> (for restrictive policies). + This is similar to the rule that a given role has the privileges + of all roles that they are a member of. Permissive vs. restrictive + policies are discussed further below. </para> <para> @@ -1899,7 +1902,7 @@ CREATE POLICY account_managers ON accounts TO managers <programlisting> CREATE POLICY user_policy ON users - USING (user = current_user); + USING (user_name = current_user); </programlisting> <para> @@ -1912,7 +1915,7 @@ CREATE POLICY user_policy ON users <programlisting> CREATE POLICY user_policy ON users USING (true) - WITH CHECK (user = current_user); + WITH CHECK (user_name = current_user); </programlisting> <para> @@ -1932,7 +1935,7 @@ CREATE POLICY user_policy ON users <programlisting> -- Simple passwd-file based example CREATE TABLE passwd ( - username text UNIQUE NOT NULL, + user_name text UNIQUE NOT NULL, pwhash text, uid int PRIMARY KEY, gid int NOT NULL, @@ -1966,9 +1969,9 @@ CREATE POLICY all_view ON passwd FOR SELECT USING (true); -- Normal users can update their own records, but -- limit which shells a normal user is allowed to set CREATE POLICY user_mod ON passwd FOR UPDATE - USING (current_user = username) + USING (current_user = user_name) WITH CHECK ( - current_user = username AND + current_user = user_name AND shell IN ('/bin/bash','/bin/sh','/bin/dash','/bin/zsh','/bin/tcsh') ); @@ -1976,7 +1979,7 @@ CREATE POLICY user_mod ON passwd FOR UPDATE GRANT SELECT, INSERT, UPDATE, DELETE ON passwd TO admin; -- Users only get select access on public columns GRANT SELECT - (username, uid, gid, real_name, home_phone, extra_info, home_dir, shell) + (user_name, uid, gid, real_name, home_phone, extra_info, home_dir, shell) ON passwd TO public; -- Allow users to update certain columns GRANT UPDATE @@ -1995,11 +1998,11 @@ GRANT UPDATE postgres=> set role admin; SET postgres=> table passwd; - username | pwhash | uid | gid | real_name | home_phone | extra_info | home_dir | shell -----------+--------+-----+-----+-----------+--------------+------------+-------------+----------- - admin | xxx | 0 | 0 | Admin | 111-222-3333 | | /root | /bin/dash - bob | xxx | 1 | 1 | Bob | 123-456-7890 | | /home/bob | /bin/zsh - alice | xxx | 2 | 1 | Alice | 098-765-4321 | | /home/alice | /bin/zsh + user_name | pwhash | uid | gid | real_name | home_phone | extra_info | home_dir | shell +-----------+--------+-----+-----+-----------+--------------+------------+-------------+----------- + admin | xxx | 0 | 0 | Admin | 111-222-3333 | | /root | /bin/dash + bob | xxx | 1 | 1 | Bob | 123-456-7890 | | /home/bob | /bin/zsh + alice | xxx | 2 | 1 | Alice | 098-765-4321 | | /home/alice | /bin/zsh (3 rows) -- Test what Alice is able to do @@ -2007,26 +2010,26 @@ postgres=> set role alice; SET postgres=> table passwd; ERROR: permission denied for relation passwd -postgres=> select username,real_name,home_phone,extra_info,home_dir,shell from passwd; - username | real_name | home_phone | extra_info | home_dir | shell -----------+-----------+--------------+------------+-------------+----------- - admin | Admin | 111-222-3333 | | /root | /bin/dash - bob | Bob | 123-456-7890 | | /home/bob | /bin/zsh - alice | Alice | 098-765-4321 | | /home/alice | /bin/zsh +postgres=> select user_name,real_name,home_phone,extra_info,home_dir,shell from passwd; + user_name | real_name | home_phone | extra_info | home_dir | shell +-----------+-----------+--------------+------------+-------------+----------- + admin | Admin | 111-222-3333 | | /root | /bin/dash + bob | Bob | 123-456-7890 | | /home/bob | /bin/zsh + alice | Alice | 098-765-4321 | | /home/alice | /bin/zsh (3 rows) -postgres=> update passwd set username = 'joe'; +postgres=> update passwd set user_name = 'joe'; ERROR: permission denied for relation passwd -- Alice is allowed to change her own real_name, but no others postgres=> update passwd set real_name = 'Alice Doe'; UPDATE 1 -postgres=> update passwd set real_name = 'John Doe' where username = 'admin'; +postgres=> update passwd set real_name = 'John Doe' where user_name = 'admin'; UPDATE 0 postgres=> update passwd set shell = '/bin/xx'; ERROR: new row violates WITH CHECK OPTION for "passwd" postgres=> delete from passwd; ERROR: permission denied for relation passwd -postgres=> insert into passwd (username) values ('xxx'); +postgres=> insert into passwd (user_name) values ('xxx'); ERROR: permission denied for relation passwd -- Alice can change her own password; RLS silently prevents updating other rows postgres=> update passwd set pwhash = 'abc'; @@ -2034,6 +2037,56 @@ UPDATE 1 </programlisting> <para> + All of the policies constructed thus far have been permissive policies, + meaning that when multiple policies are applied they are combined using + the "OR" boolean operator. While permissive policies can be constructed + to only allow access to rows in the intended cases, it can be simpler to + combine permissive policies with restrictive policies (which the records + must pass and which are combined using the "AND" boolean operator). + Building on the example above, we add a restrictive policy to require + the administrator to be connected over a local unix socket to access the + records of the passwd table: + </para> + +<programlisting> +CREATE POLICY admin_local_only ON passwd AS RESTRICTIVE TO admin + USING (pg_catalog.inet_client_addr() IS NULL); +</programlisting> + + <para> + We can then see that an administrator connecting over a network will not + see any records, due to the restrictive policy: + </para> + +<programlisting> +=> SELECT current_user; + current_user +-------------- + admin +(1 row) + +=> select inet_client_addr(); + inet_client_addr +------------------ + 127.0.0.1 +(1 row) + +=> SELECT current_user; + current_user +-------------- + admin +(1 row) + +=> TABLE passwd; + user_name | pwhash | uid | gid | real_name | home_phone | extra_info | home_dir | shell +-----------+--------+-----+-----+-----------+------------+------------+----------+------- +(0 rows) + +=> UPDATE passwd set pwhash = NULL; +UPDATE 0 +</programlisting> + + <para> Referential integrity checks, such as unique or primary key constraints and foreign key references, always bypass row security to ensure that data integrity is maintained. Care must be taken when developing @@ -2325,7 +2378,7 @@ DROP SCHEMA myschema CASCADE; (since this is one of the ways to restrict the activities of your users to well-defined namespaces). The syntax for that is: <programlisting> -CREATE SCHEMA <replaceable>schemaname</replaceable> AUTHORIZATION <replaceable>username</replaceable>; +CREATE SCHEMA <replaceable>schema_name</replaceable> AUTHORIZATION <replaceable>user_name</replaceable>; </programlisting> You can even omit the schema name, in which case the schema name will be the same as the user name. See <xref @@ -2614,7 +2667,7 @@ REVOKE CREATE ON SCHEMA public FROM PUBLIC; implements only the basic schema support specified in the standard. Therefore, many users consider qualified names to really consist of - <literal><replaceable>username</>.<replaceable>tablename</></literal>. + <literal><replaceable>user_name</>.<replaceable>table_name</></literal>. This is how <productname>PostgreSQL</productname> will effectively behave if you create a per-user schema for every user. </para> @@ -2747,11 +2800,9 @@ SELECT name, altitude WHERE altitude > 500; </programlisting> - Writing <literal>*</> is not necessary, since this behavior is - the default (unless you have changed the setting of the - <xref linkend="guc-sql-inheritance"> configuration option). - However writing <literal>*</> might be useful to emphasize that - additional tables will be searched. + Writing <literal>*</> is not necessary, since this behavior is always + the default. However, this syntax is still supported for + compatibility with older releases where the default could be changed. </para> <para> @@ -2799,7 +2850,7 @@ WHERE c.altitude > 500 AND c.tableoid = p.oid; <para> Another way to get the same effect is to use the <type>regclass</> - pseudo-type, which will print the table OID symbolically: + alias type, which will print the table OID symbolically: <programlisting> SELECT c.tableoid::regclass, c.name, c.altitude @@ -2829,7 +2880,8 @@ VALUES ('Albany', NULL, NULL, 'NY'); <para> All check constraints and not-null constraints on a parent table are - automatically inherited by its children. Other types of constraints + automatically inherited by its children, unless explicitly specified + otherwise with <literal>NO INHERIT</> clauses. Other types of constraints (unique, primary key, and foreign key constraints) are not inherited. </para> @@ -2840,10 +2892,12 @@ VALUES ('Albany', NULL, NULL, 'NY'); same column name appears in multiple parent tables, or in both a parent table and the child's definition, then these columns are <quote>merged</> so that there is only one such column in the child table. To be merged, - columns must have the same data types, else an error is raised. The - merged column will have copies of all the check constraints coming from - any one of the column definitions it came from, and will be marked not-null - if any of them are. + columns must have the same data types, else an error is raised. + Inheritable check constraints and not-null constraints are merged in a + similar fashion. Thus, for example, a merged column will be marked + not-null if any one of the column definitions it came from is marked + not-null. Check constraints are merged if they have the same name, + and the merge will fail if their conditions are different. </para> <para> @@ -2895,12 +2949,19 @@ VALUES ('Albany', NULL, NULL, 'NY'); </para> <para> - Note how table access permissions are handled. Querying a parent - table can automatically access data in child tables without further - access privilege checking. This preserves the appearance that the - data is (also) in the parent table. Accessing the child tables - directly is, however, not automatically allowed and would require - further privileges to be granted. + Inherited queries perform access permission checks on the parent table + only. Thus, for example, granting <literal>UPDATE</> permission on + the <structname>cities</> table implies permission to update rows in + the <structname>capitals</structname> table as well, when they are + accessed through <structname>cities</>. This preserves the appearance + that the data is (also) in the parent table. But + the <structname>capitals</structname> table could not be updated directly + without an additional grant. In a similar way, the parent table's row + security policies (see <xref linkend="ddl-rowsecurity">) are applied to + rows coming from child tables during an inherited query. A child table's + policies, if any, are applied only when it is the table explicitly named + in the query; and in that case, any policies attached to its parent(s) are + ignored. </para> <para> @@ -2982,7 +3043,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); </sect1> <sect1 id="ddl-partitioning"> - <title>Partitioning</title> + <title>Table Partitioning</title> <indexterm> <primary>partitioning</primary> @@ -2993,6 +3054,10 @@ VALUES ('Albany', NULL, NULL, 'NY'); <secondary>partitioning</secondary> </indexterm> + <indexterm> + <primary>partitioned table</primary> + </indexterm> + <para> <productname>PostgreSQL</productname> supports basic table partitioning. This section describes why and how to implement @@ -3002,308 +3067,673 @@ VALUES ('Albany', NULL, NULL, 'NY'); <sect2 id="ddl-partitioning-overview"> <title>Overview</title> - <para> - Partitioning refers to splitting what is logically one large table - into smaller physical pieces. - Partitioning can provide several benefits: - <itemizedlist> - <listitem> - <para> - Query performance can be improved dramatically in certain situations, - particularly when most of the heavily accessed rows of the table are in a - single partition or a small number of partitions. The partitioning - substitutes for leading columns of indexes, reducing index size and - making it more likely that the heavily-used parts of the indexes - fit in memory. - </para> - </listitem> + <para> + Partitioning refers to splitting what is logically one large table into + smaller physical pieces. Partitioning can provide several benefits: + <itemizedlist> + <listitem> + <para> + Query performance can be improved dramatically in certain situations, + particularly when most of the heavily accessed rows of the table are in a + single partition or a small number of partitions. The partitioning + substitutes for leading columns of indexes, reducing index size and + making it more likely that the heavily-used parts of the indexes + fit in memory. + </para> + </listitem> - <listitem> - <para> - When queries or updates access a large percentage of a single - partition, performance can be improved by taking advantage - of sequential scan of that partition instead of using an - index and random access reads scattered across the whole table. - </para> - </listitem> + <listitem> + <para> + When queries or updates access a large percentage of a single + partition, performance can be improved by taking advantage + of sequential scan of that partition instead of using an + index and random access reads scattered across the whole table. + </para> + </listitem> - <listitem> - <para> - Bulk loads and deletes can be accomplished by adding or removing - partitions, if that requirement is planned into the partitioning design. - <command>ALTER TABLE NO INHERIT</> and <command>DROP TABLE</> are - both far faster than a bulk operation. - These commands also entirely avoid the <command>VACUUM</command> - overhead caused by a bulk <command>DELETE</>. - </para> - </listitem> + <listitem> + <para> + Bulk loads and deletes can be accomplished by adding or removing + partitions, if that requirement is planned into the partitioning design. + Doing <command>ALTER TABLE DETACH PARTITION</> or dropping an individual + partition using <command>DROP TABLE</> is far faster than a bulk + operation. These commands also entirely avoid the + <command>VACUUM</command> overhead caused by a bulk <command>DELETE</>. + </para> + </listitem> - <listitem> - <para> - Seldom-used data can be migrated to cheaper and slower storage media. - </para> - </listitem> - </itemizedlist> + <listitem> + <para> + Seldom-used data can be migrated to cheaper and slower storage media. + </para> + </listitem> + </itemizedlist> + + The benefits will normally be worthwhile only when a table would + otherwise be very large. The exact point at which a table will + benefit from partitioning depends on the application, although a + rule of thumb is that the size of the table should exceed the physical + memory of the database server. + </para> + + <para> + <productname>PostgreSQL</productname> offers built-in support for the + following forms of partitioning: + + <variablelist> + <varlistentry> + <term>Range Partitioning</term> - The benefits will normally be worthwhile only when a table would - otherwise be very large. The exact point at which a table will - benefit from partitioning depends on the application, although a - rule of thumb is that the size of the table should exceed the physical - memory of the database server. + <listitem> + <para> + The table is partitioned into <quote>ranges</quote> defined + by a key column or set of columns, with no overlap between + the ranges of values assigned to different partitions. For + example, one might partition by date ranges, or by ranges of + identifiers for particular business objects. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>List Partitioning</term> + + <listitem> + <para> + The table is partitioned by explicitly listing which key values + appear in each partition. + </para> + </listitem> + </varlistentry> + </variablelist> + + If your application needs to use other forms of partitioning not listed + above, alternative methods such as inheritance and + <literal>UNION ALL</literal> views can be used instead. Such methods + offer flexibility but do not have some of the performance benefits + of built-in declarative partitioning. + </para> + </sect2> + + <sect2 id="ddl-partitioning-declarative"> + <title>Declarative Partitioning</title> + + <para> + <productname>PostgreSQL</productname> offers a way to specify how to + divide a table into pieces called partitions. The table that is divided + is referred to as a <firstterm>partitioned table</firstterm>. The + specification consists of the <firstterm>partitioning method</firstterm> + and a list of columns or expressions to be used as the + <firstterm>partition key</firstterm>. </para> <para> - Currently, <productname>PostgreSQL</productname> supports partitioning - via table inheritance. Each partition must be created as a child - table of a single parent table. The parent table itself is normally - empty; it exists just to represent the entire data set. You should be - familiar with inheritance (see <xref linkend="ddl-inherit">) before - attempting to set up partitioning. + All rows inserted into a partitioned table will be routed to one of the + <firstterm>partitions</firstterm> based on the value of the partition + key. Each partition has a subset of the data defined by its + <firstterm>partition bounds</firstterm>. Currently supported + partitioning methods include range and list, where each partition is + assigned a range of keys and a list of keys, respectively. </para> <para> - The following forms of partitioning can be implemented in - <productname>PostgreSQL</productname>: + Partitions may themselves be defined as partitioned tables, using what is + called <firstterm>sub-partitioning</firstterm>. Partitions may have their + own indexes, constraints and default values, distinct from those of other + partitions. Indexes must be created separately for each partition. See + <xref linkend="sql-createtable"> for more details on creating partitioned + tables and partitions. + </para> - <variablelist> - <varlistentry> - <term>Range Partitioning</term> + <para> + It is not possible to turn a regular table into a partitioned table or + vice versa. However, it is possible to add a regular or partitioned table + containing data as a partition of a partitioned table, or remove a + partition from a partitioned table turning it into a standalone table; + see <xref linkend="sql-altertable"> to learn more about the + <command>ATTACH PARTITION</> and <command>DETACH PARTITION</> + sub-commands. + </para> - <listitem> - <para> - The table is partitioned into <quote>ranges</quote> defined - by a key column or set of columns, with no overlap between - the ranges of values assigned to different partitions. For - example one might partition by date ranges, or by ranges of - identifiers for particular business objects. - </para> - </listitem> - </varlistentry> + <para> + Individual partitions are linked to the partitioned table with inheritance + behind-the-scenes; however, it is not possible to use some of the + inheritance features discussed in the previous section with partitioned + tables and partitions. For example, a partition cannot have any parents + other than the partitioned table it is a partition of, nor can a regular + table inherit from a partitioned table making the latter its parent. + That means partitioned tables and partitions do not participate in + inheritance with regular tables. Since a partition hierarchy consisting + of the partitioned table and its partitions is still an inheritance + hierarchy, all the normal rules of inheritance apply as described in + <xref linkend="ddl-inherit"> with some exceptions, most notably: - <varlistentry> - <term>List Partitioning</term> + <itemizedlist> + <listitem> + <para> + Both <literal>CHECK</literal> and <literal>NOT NULL</literal> + constraints of a partitioned table are always inherited by all its + partitions. <literal>CHECK</literal> constraints that are marked + <literal>NO INHERIT</literal> are not allowed to be created on + partitioned tables. + </para> + </listitem> - <listitem> - <para> - The table is partitioned by explicitly listing which key values - appear in each partition. - </para> - </listitem> - </varlistentry> - </variablelist> + <listitem> + <para> + Using <literal>ONLY</literal> to add or drop a constraint on only the + partitioned table is supported when there are no partitions. Once + partitions exist, using <literal>ONLY</literal> will result in an error + as adding or dropping constraints on only the partitioned table, when + partitions exist, is not supported. Instead, constraints can be added + or dropped, when they are not present in the parent table, directly on + the partitions. As a partitioned table does not have any data + directly, attempts to use <command>TRUNCATE</command> + <literal>ONLY</literal> on a partitioned table will always return an + error. + </para> + </listitem> + + <listitem> + <para> + Partitions cannot have columns that are not present in the parent. It + is neither possible to specify columns when creating partitions with + <command>CREATE TABLE</> nor is it possible to add columns to + partitions after-the-fact using <command>ALTER TABLE</>. Tables may be + added as a partition with <command>ALTER TABLE ... ATTACH PARTITION</> + only if their columns exactly match the parent, including oids. + </para> + </listitem> + + <listitem> + <para> + You cannot drop the <literal>NOT NULL</literal> constraint on a + partition's column if the constraint is present in the parent table. + </para> + </listitem> + </itemizedlist> </para> - </sect2> - <sect2 id="ddl-partitioning-implementation"> - <title>Implementing Partitioning</title> + <para> + Partitions can also be foreign tables + (see <xref linkend="sql-createforeigntable">), + although these have some limitations that normal tables do not. For + example, data inserted into the partitioned table is not routed to + foreign table partitions. + </para> - <para> - To set up a partitioned table, do the following: - <orderedlist spacing="compact"> - <listitem> - <para> - Create the <quote>master</quote> table, from which all of the - partitions will inherit. - </para> - <para> - This table will contain no data. Do not define any check - constraints on this table, unless you intend them to - be applied equally to all partitions. There is no point - in defining any indexes or unique constraints on it, either. - </para> - </listitem> + <sect3 id="ddl-partitioning-declarative-example"> + <title>Example</title> - <listitem> - <para> - Create several <quote>child</quote> tables that each inherit from - the master table. Normally, these tables will not add any columns - to the set inherited from the master. - </para> + <para> + Suppose we are constructing a database for a large ice cream company. + The company measures peak temperatures every day as well as ice cream + sales in each region. Conceptually, we want a table like: - <para> - We will refer to the child tables as partitions, though they - are in every way normal <productname>PostgreSQL</> tables - (or, possibly, foreign tables). - </para> - </listitem> +<programlisting> +CREATE TABLE measurement ( + city_id int not null, + logdate date not null, + peaktemp int, + unitsales int +); +</programlisting> - <listitem> - <para> - Add table constraints to the partition tables to define the - allowed key values in each partition. - </para> + We know that most queries will access just the last week's, month's or + quarter's data, since the main use of this table will be to prepare + online reports for management. To reduce the amount of old data that + needs to be stored, we decide to only keep the most recent 3 years + worth of data. At the beginning of each month we will remove the oldest + month's data. In this situation we can use partitioning to help us meet + all of our different requirements for the measurements table. + </para> + + <para> + To use declarative partitioning in this case, use the following steps: + + <orderedlist spacing="compact"> + <listitem> + <para> + Create <structname>measurement</structname> table as a partitioned + table by specifying the <literal>PARTITION BY</literal> clause, which + includes the partitioning method (<literal>RANGE</literal> in this + case) and the list of column(s) to use as the partition key. - <para> - Typical examples would be: <programlisting> -CHECK ( x = 1 ) -CHECK ( county IN ( 'Oxfordshire', 'Buckinghamshire', 'Warwickshire' )) -CHECK ( outletID >= 100 AND outletID < 200 ) +CREATE TABLE measurement ( + city_id int not null, + logdate date not null, + peaktemp int, + unitsales int +) PARTITION BY RANGE (logdate); </programlisting> - Ensure that the constraints guarantee that there is no overlap - between the key values permitted in different partitions. A common - mistake is to set up range constraints like: + </para> + + <para> + You may decide to use multiple columns in the partition key for range + partitioning, if desired. Of course, this will often result in a larger + number of partitions, each of which is individually smaller. On the + other hand, using fewer columns may lead to a coarser-grained + partitioning criteria with smaller number of partitions. A query + accessing the partitioned table will have to scan fewer partitions if + the conditions involve some or all of these columns. + For example, consider a table range partitioned using columns + <structfield>lastname</> and <structfield>firstname</> (in that order) + as the partition key. + </para> + </listitem> + + <listitem> + <para> + Create partitions. Each partition's definition must specify the bounds + that correspond to the partitioning method and partition key of the + parent. Note that specifying bounds such that the new partition's + values will overlap with those in one or more existing partitions will + cause an error. Inserting data into the parent table that does not map + to one of the existing partitions will cause an error; appropriate + partition must be added manually. + </para> + + <para> + Partitions thus created are in every way normal + <productname>PostgreSQL</> + tables (or, possibly, foreign tables). It is possible to specify a + tablespace and storage parameters for each partition separately. + </para> + + <para> + It is not necessary to create table constraints describing partition + boundary condition for partitions. Instead, partition constraints are + generated implicitly from the partition bound specification whenever + there is need to refer to them. + <programlisting> -CHECK ( outletID BETWEEN 100 AND 200 ) -CHECK ( outletID BETWEEN 200 AND 300 ) +CREATE TABLE measurement_y2006m02 PARTITION OF measurement + FOR VALUES FROM ('2006-02-01') TO ('2006-03-01') + +CREATE TABLE measurement_y2006m03 PARTITION OF measurement + FOR VALUES FROM ('2006-03-01') TO ('2006-04-01') + +... +CREATE TABLE measurement_y2007m11 PARTITION OF measurement + FOR VALUES FROM ('2007-11-01') TO ('2007-12-01') + +CREATE TABLE measurement_y2007m12 PARTITION OF measurement + FOR VALUES FROM ('2007-12-01') TO ('2008-01-01') + TABLESPACE fasttablespace; + +CREATE TABLE measurement_y2008m01 PARTITION OF measurement + FOR VALUES FROM ('2008-01-01') TO ('2008-02-01') + TABLESPACE fasttablespace + WITH (parallel_workers = 4); </programlisting> - This is wrong since it is not clear which partition the key value - 200 belongs in. - </para> + </para> - <para> - Note that there is no difference in - syntax between range and list partitioning; those terms are - descriptive only. - </para> - </listitem> + <para> + To implement sub-partitioning, specify the + <literal>PARTITION BY</literal> clause in the commands used to create + individual partitions, for example: - <listitem> - <para> - For each partition, create an index on the key column(s), - as well as any other indexes you might want. (The key index is - not strictly necessary, but in most scenarios it is helpful. - If you intend the key values to be unique then you should - always create a unique or primary-key constraint for each - partition.) - </para> - </listitem> +<programlisting> +CREATE TABLE measurement_y2006m02 PARTITION OF measurement + FOR VALUES FROM ('2006-02-01') TO ('2006-03-01') + PARTITION BY RANGE (peaktemp); +</programlisting> - <listitem> - <para> - Optionally, define a trigger or rule to redirect data inserted into - the master table to the appropriate partition. - </para> - </listitem> + After creating partitions of <structname>measurement_y2006m02</>, + any data inserted into <structname>measurement</> that is mapped to + <structname>measurement_y2006m02</> (or data that is directly inserted + into <structname>measurement_y2006m02</>, provided it satisfies its + partition constraint) will be further redirected to one of its + partitions based on the <structfield>peaktemp</> column. The partition + key specified may overlap with the parent's partition key, although + care should be taken when specifying the bounds of a sub-partition + such that the set of data it accepts constitutes a subset of what + the partition's own bounds allows; the system does not try to check + whether that's really the case. + </para> + </listitem> + + <listitem> + <para> + Create an index on the key column(s), as well as any other indexes you + might want for every partition. (The key index is not strictly + necessary, but in most scenarios it is helpful. If you intend the key + values to be unique then you should always create a unique or + primary-key constraint for each partition.) + +<programlisting> +CREATE INDEX ON measurement_y2006m02 (logdate); +CREATE INDEX ON measurement_y2006m03 (logdate); +... +CREATE INDEX ON measurement_y2007m11 (logdate); +CREATE INDEX ON measurement_y2007m12 (logdate); +CREATE INDEX ON measurement_y2008m01 (logdate); +</programlisting> + </para> + </listitem> <listitem> <para> Ensure that the <xref linkend="guc-constraint-exclusion"> - configuration parameter is not disabled in - <filename>postgresql.conf</>. + configuration parameter is not disabled in <filename>postgresql.conf</>. If it is, queries will not be optimized as desired. </para> </listitem> + </orderedlist> + </para> + + <para> + In the above example we would be creating a new partition each month, so + it might be wise to write a script that generates the required DDL + automatically. + </para> + </sect3> + + <sect3 id="ddl-partitioning-declarative-maintenance"> + <title>Partition Maintenance</title> - </orderedlist> + <para> + Normally the set of partitions established when initially defining the + the table are not intended to remain static. It is common to want to + remove old partitions of data and periodically add new partitions for + new data. One of the most important advantages of partitioning is + precisely that it allows this otherwise painful task to be executed + nearly instantaneously by manipulating the partition structure, rather + than physically moving large amounts of data around. </para> <para> - For example, suppose we are constructing a database for a large - ice cream company. The company measures peak temperatures every - day as well as ice cream sales in each region. Conceptually, - we want a table like: + The simplest option for removing old data is to drop the partition that + is no longer necessary: +<programlisting> +DROP TABLE measurement_y2006m02; +</programlisting> + This can very quickly delete millions of records because it doesn't have + to individually delete every record. Note however that the above command + requires taking an <literal>ACCESS EXCLUSIVE</literal> lock on the parent + table. + </para> + + <para> + Another option that is often preferable is to remove the partition from + the partitioned table but retain access to it as a table in its own + right: <programlisting> -CREATE TABLE measurement ( - city_id int not null, - logdate date not null, - peaktemp int, - unitsales int -); +ALTER TABLE measurement DETACH PARTITION measurement_y2006m02; +</programlisting> + + This allows further operations to be performed on the data before + it is dropped. For example, this is often a useful time to back up + the data using <command>COPY</>, <application>pg_dump</>, or + similar tools. It might also be a useful time to aggregate data + into smaller formats, perform other data manipulations, or run + reports. + </para> + + <para> + Similarly we can add a new partition to handle new data. We can create an + empty partition in the partitioned table just as the original partitions + were created above: + +<programlisting> +CREATE TABLE measurement_y2008m02 PARTITION OF measurement + FOR VALUES FROM ('2008-02-01') TO ('2008-03-01') + TABLESPACE fasttablespace; </programlisting> - We know that most queries will access just the last week's, month's or - quarter's data, since the main use of this table will be to prepare - online reports for management. - To reduce the amount of old data that needs to be stored, we - decide to only keep the most recent 3 years worth of data. At the - beginning of each month we will remove the oldest month's data. + As an alternative, it is sometimes more convenient to create the + new table outside the partition structure, and make it a proper + partition later. This allows the data to be loaded, checked, and + transformed prior to it appearing in the partitioned table: + +<programlisting> +CREATE TABLE measurement_y2008m02 + (LIKE measurement INCLUDING DEFAULTS INCLUDING CONSTRAINTS) + TABLESPACE fasttablespace; + +ALTER TABLE measurement_y2008m02 ADD CONSTRAINT y2008m02 + CHECK ( logdate >= DATE '2008-02-01' AND logdate < DATE '2008-03-01' ); + +\copy measurement_y2008m02 from 'measurement_y2008m02' +-- possibly some other data preparation work + +ALTER TABLE measurement ATTACH PARTITION measurement_y2008m02 + FOR VALUES FROM ('2008-02-01') TO ('2008-03-01' ); +</programlisting> </para> <para> - In this situation we can use partitioning to help us meet all of our - different requirements for the measurements table. Following the - steps outlined above, partitioning can be set up as follows: + Before running the <command>ATTACH PARTITION</> command, it is + recommended to create a <literal>CHECK</> constraint on the table to + be attached describing the desired partition constraint. That way, + the system will be able to skip the scan to validate the implicit + partition constraint. Without such a constraint, the table will be + scanned to validate the partition constraint while holding an + <literal>ACCESS EXCLUSIVE</literal> lock on the parent table. + One may then drop the constraint after <command>ATTACH PARTITION</> + is finished, because it is no longer necessary. </para> + </sect3> + <sect3 id="ddl-partitioning-declarative-limitations"> + <title>Limitations</title> + + <para> + The following limitations apply to partitioned tables: + <itemizedlist> + <listitem> + <para> + There is no facility available to create the matching indexes on all + partitions automatically. Indexes must be added to each partition with + separate commands. This also means that there is no way to create a + primary key, unique constraint, or exclusion constraint spanning all + partitions; it is only possible to constrain each leaf partition + individually. + </para> + </listitem> + + <listitem> + <para> + Since primary keys are not supported on partitioned tables, foreign + keys referencing partitioned tables are not supported, nor are foreign + key references from a partitioned table to some other table. + </para> + </listitem> + + <listitem> + <para> + Using the <literal>ON CONFLICT</literal> clause with partitioned tables + will cause an error, because unique or exclusion constraints can only be + created on individual partitions. There is no support for enforcing + uniqueness (or an exclusion constraint) across an entire partitioning + hierarchy. + </para> + </listitem> + + <listitem> + <para> + An <command>UPDATE</> that causes a row to move from one partition to + another fails, because the new value of the row fails to satisfy the + implicit partition constraint of the original partition. + </para> + </listitem> + + <listitem> + <para> + Row triggers, if necessary, must be defined on individual partitions, + not the partitioned table. + </para> + </listitem> + </itemizedlist> + </para> + </sect3> + </sect2> + + <sect2 id="ddl-partitioning-implementation-inheritance"> + <title>Implementation Using Inheritance</title> <para> - <orderedlist spacing="compact"> + While the built-in declarative partitioning is suitable for most + common use cases, there are some circumstances where a more flexible + approach may be useful. Partitioning can be implemented using table + inheritance, which allows for several features which are not supported + by declarative partitioning, such as: + + <itemizedlist> <listitem> <para> - The master table is the <structname>measurement</> table, declared - exactly as above. + Partitioning enforces a rule that all partitions must have exactly + the same set of columns as the parent, but table inheritance allows + children to have extra columns not present in the parent. </para> </listitem> <listitem> <para> - Next we create one partition for each active month: - -<programlisting> -CREATE TABLE measurement_y2006m02 ( ) INHERITS (measurement); -CREATE TABLE measurement_y2006m03 ( ) INHERITS (measurement); -... -CREATE TABLE measurement_y2007m11 ( ) INHERITS (measurement); -CREATE TABLE measurement_y2007m12 ( ) INHERITS (measurement); -CREATE TABLE measurement_y2008m01 ( ) INHERITS (measurement); -</programlisting> - - Each of the partitions are complete tables in their own right, - but they inherit their definitions from the - <structname>measurement</> table. + Table inheritance allows for multiple inheritance. </para> + </listitem> + <listitem> <para> - This solves one of our problems: deleting old data. Each - month, all we will need to do is perform a <command>DROP - TABLE</command> on the oldest child table and create a new - child table for the new month's data. + Declarative partitioning only supports list and range partitioning, + whereas table inheritance allows data to be divided in a manner of + the user's choosing. (Note, however, that if constraint exclusion is + unable to prune partitions effectively, query performance will be very + poor.) </para> </listitem> <listitem> <para> - We must provide non-overlapping table constraints. Rather than - just creating the partition tables as above, the table creation - script should really be: + Some operations require a stronger lock when using declarative + partitioning than when using table inheritance. For example, adding + or removing a partition to or from a partitioned table requires taking + an <literal>ACCESS EXCLUSIVE</literal> lock on the parent table, + whereas a <literal>SHARE UPDATE EXCLUSIVE</literal> lock is enough + in the case of regular inheritance. + </para> + </listitem> + </itemizedlist> + </para> + + <sect3 id="ddl-partitioning-inheritance-example"> + <title>Example</title> + + <para> + We use the same <structname>measurement</structname> table we used + above. To implement it as a partitioned table using inheritance, use + the following steps: + + <orderedlist spacing="compact"> + <listitem> + <para> + Create the <quote>master</quote> table, from which all of the + partitions will inherit. This table will contain no data. Do not + define any check constraints on this table, unless you intend them + to be applied equally to all partitions. There is no point in + defining any indexes or unique constraints on it, either. For our + example, master table is the <structname>measurement</structname> + table as originally defined. + </para> + </listitem> + + <listitem> + <para> + Create several <quote>child</quote> tables that each inherit from + the master table. Normally, these tables will not add any columns + to the set inherited from the master. Just as with declarative + partitioning, these partitions are in every way normal + <productname>PostgreSQL</> tables (or foreign tables). + </para> + + <para> +<programlisting> +CREATE TABLE measurement_y2006m02 () INHERITS (measurement); +CREATE TABLE measurement_y2006m03 () INHERITS (measurement); +... +CREATE TABLE measurement_y2007m11 () INHERITS (measurement); +CREATE TABLE measurement_y2007m12 () INHERITS (measurement); +CREATE TABLE measurement_y2008m01 () INHERITS (measurement); +</programlisting> + </para> + </listitem> + + <listitem> + <para> + Add non-overlapping table constraints to the partition tables to + define the allowed key values in each partition. + </para> + + <para> + Typical examples would be: +<programlisting> +CHECK ( x = 1 ) +CHECK ( county IN ( 'Oxfordshire', 'Buckinghamshire', 'Warwickshire' )) +CHECK ( outletID >= 100 AND outletID < 200 ) +</programlisting> + Ensure that the constraints guarantee that there is no overlap + between the key values permitted in different partitions. A common + mistake is to set up range constraints like: +<programlisting> +CHECK ( outletID BETWEEN 100 AND 200 ) +CHECK ( outletID BETWEEN 200 AND 300 ) +</programlisting> + This is wrong since it is not clear which partition the key value + 200 belongs in. + </para> + + <para> + It would be better to instead create partitions as follows: <programlisting> CREATE TABLE measurement_y2006m02 ( CHECK ( logdate >= DATE '2006-02-01' AND logdate < DATE '2006-03-01' ) ) INHERITS (measurement); + CREATE TABLE measurement_y2006m03 ( CHECK ( logdate >= DATE '2006-03-01' AND logdate < DATE '2006-04-01' ) ) INHERITS (measurement); + ... CREATE TABLE measurement_y2007m11 ( CHECK ( logdate >= DATE '2007-11-01' AND logdate < DATE '2007-12-01' ) ) INHERITS (measurement); + CREATE TABLE measurement_y2007m12 ( CHECK ( logdate >= DATE '2007-12-01' AND logdate < DATE '2008-01-01' ) ) INHERITS (measurement); + CREATE TABLE measurement_y2008m01 ( CHECK ( logdate >= DATE '2008-01-01' AND logdate < DATE '2008-02-01' ) ) INHERITS (measurement); </programlisting> - </para> - </listitem> - - <listitem> - <para> - We probably need indexes on the key columns too: + </para> + </listitem> + <listitem> + <para> + For each partition, create an index on the key column(s), + as well as any other indexes you might want. <programlisting> CREATE INDEX measurement_y2006m02_logdate ON measurement_y2006m02 (logdate); CREATE INDEX measurement_y2006m03_logdate ON measurement_y2006m03 (logdate); -... CREATE INDEX measurement_y2007m11_logdate ON measurement_y2007m11 (logdate); CREATE INDEX measurement_y2007m12_logdate ON measurement_y2007m12 (logdate); CREATE INDEX measurement_y2008m01_logdate ON measurement_y2008m01 (logdate); </programlisting> + </para> + </listitem> - We choose not to add further indexes at this time. - </para> - </listitem> - - <listitem> - <para> - We want our application to be able to say <literal>INSERT INTO - measurement ...</> and have the data be redirected into the - appropriate partition table. We can arrange that by attaching - a suitable trigger function to the master table. - If data will be added only to the latest partition, we can - use a very simple trigger function: + <listitem> + <para> + We want our application to be able to say <literal>INSERT INTO + measurement ...</> and have the data be redirected into the + appropriate partition table. We can arrange that by attaching + a suitable trigger function to the master table. + If data will be added only to the latest partition, we can + use a very simple trigger function: <programlisting> CREATE OR REPLACE FUNCTION measurement_insert_trigger() @@ -3315,9 +3745,11 @@ END; $$ LANGUAGE plpgsql; </programlisting> + </para> - After creating the function, we create a trigger which - calls the trigger function: + <para> + After creating the function, we create a trigger which + calls the trigger function: <programlisting> CREATE TRIGGER insert_measurement_trigger @@ -3325,15 +3757,15 @@ CREATE TRIGGER insert_measurement_trigger FOR EACH ROW EXECUTE PROCEDURE measurement_insert_trigger(); </programlisting> - We must redefine the trigger function each month so that it always - points to the current partition. The trigger definition does - not need to be updated, however. - </para> + We must redefine the trigger function each month so that it always + points to the current partition. The trigger definition does + not need to be updated, however. + </para> - <para> - We might want to insert data and have the server automatically - locate the partition into which the row should be added. We - could do this with a more complex trigger function, for example: + <para> + We might want to insert data and have the server automatically + locate the partition into which the row should be added. We + could do this with a more complex trigger function, for example: <programlisting> CREATE OR REPLACE FUNCTION measurement_insert_trigger() @@ -3358,81 +3790,107 @@ $$ LANGUAGE plpgsql; </programlisting> - The trigger definition is the same as before. - Note that each <literal>IF</literal> test must exactly match the - <literal>CHECK</literal> constraint for its partition. - </para> + The trigger definition is the same as before. + Note that each <literal>IF</literal> test must exactly match the + <literal>CHECK</literal> constraint for its partition. + </para> - <para> - While this function is more complex than the single-month case, - it doesn't need to be updated as often, since branches can be - added in advance of being needed. - </para> + <para> + While this function is more complex than the single-month case, + it doesn't need to be updated as often, since branches can be + added in advance of being needed. + </para> + + <note> + <para> + In practice it might be best to check the newest partition first, + if most inserts go into that partition. For simplicity we have + shown the trigger's tests in the same order as in other parts + of this example. + </para> + </note> - <note> <para> - In practice it might be best to check the newest partition first, - if most inserts go into that partition. For simplicity we have - shown the trigger's tests in the same order as in other parts - of this example. + A different approach to redirecting inserts into the appropriate + partition table is to set up rules, instead of a trigger, on the + master table. For example: + +<programlisting> +CREATE RULE measurement_insert_y2006m02 AS +ON INSERT TO measurement WHERE + ( logdate >= DATE '2006-02-01' AND logdate < DATE '2006-03-01' ) +DO INSTEAD + INSERT INTO measurement_y2006m02 VALUES (NEW.*); +... +CREATE RULE measurement_insert_y2008m01 AS +ON INSERT TO measurement WHERE + ( logdate >= DATE '2008-01-01' AND logdate < DATE '2008-02-01' ) +DO INSTEAD + INSERT INTO measurement_y2008m01 VALUES (NEW.*); +</programlisting> + + A rule has significantly more overhead than a trigger, but the + overhead is paid once per query rather than once per row, so this + method might be advantageous for bulk-insert situations. In most + cases, however, the trigger method will offer better performance. </para> - </note> - </listitem> - </orderedlist> - </para> - <para> - As we can see, a complex partitioning scheme could require a - substantial amount of DDL. In the above example we would be - creating a new partition each month, so it might be wise to write a - script that generates the required DDL automatically. - </para> + <para> + Be aware that <command>COPY</> ignores rules. If you want to + use <command>COPY</> to insert data, you'll need to copy into the + correct partition table rather than into the master. <command>COPY</> + does fire triggers, so you can use it normally if you use the trigger + approach. + </para> - </sect2> + <para> + Another disadvantage of the rule approach is that there is no simple + way to force an error if the set of rules doesn't cover the insertion + date; the data will silently go into the master table instead. + </para> + </listitem> - <sect2 id="ddl-partitioning-managing-partitions"> - <title>Managing Partitions</title> + <listitem> + <para> + Ensure that the <xref linkend="guc-constraint-exclusion"> + configuration parameter is not disabled in + <filename>postgresql.conf</>. + If it is, queries will not be optimized as desired. + </para> + </listitem> + </orderedlist> + </para> - <para> - Normally the set of partitions established when initially - defining the table are not intended to remain static. It is - common to want to remove old partitions of data and periodically - add new partitions for new data. One of the most important - advantages of partitioning is precisely that it allows this - otherwise painful task to be executed nearly instantaneously by - manipulating the partition structure, rather than physically moving large - amounts of data around. - </para> + <para> + As we can see, a complex partitioning scheme could require a + substantial amount of DDL. In the above example we would be creating + a new partition each month, so it might be wise to write a script that + generates the required DDL automatically. + </para> + </sect3> - <para> - The simplest option for removing old data is simply to drop the partition - that is no longer necessary: + <sect3 id="ddl-partitioning-inheritance-maintenance"> + <title>Partition Maintenance</title> + <para> + To remove old data quickly, simply drop the partition that is no longer + necessary: <programlisting> DROP TABLE measurement_y2006m02; </programlisting> - This can very quickly delete millions of records because it doesn't have - to individually delete every record. - </para> + </para> + + <para> + To remove the partition from the partitioned table but retain access to + it as a table in its own right: - <para> - Another option that is often preferable is to remove the partition from - the partitioned table but retain access to it as a table in its own - right: <programlisting> ALTER TABLE measurement_y2006m02 NO INHERIT measurement; </programlisting> - This allows further operations to be performed on the data before - it is dropped. For example, this is often a useful time to back up - the data using <command>COPY</>, <application>pg_dump</>, or - similar tools. It might also be a useful time to aggregate data - into smaller formats, perform other data manipulations, or run - reports. - </para> + </para> - <para> - Similarly we can add a new partition to handle new data. We can create an - empty partition in the partitioned table just as the original partitions - were created above: + <para> + To add a new partition to handle new data, create an empty partition + just as the original partitions were created above: <programlisting> CREATE TABLE measurement_y2008m02 ( @@ -3440,10 +3898,9 @@ CREATE TABLE measurement_y2008m02 ( ) INHERITS (measurement); </programlisting> - As an alternative, it is sometimes more convenient to create the - new table outside the partition structure, and make it a proper - partition later. This allows the data to be loaded, checked, and - transformed prior to it appearing in the partitioned table: + Alternatively, one may want to create the new table outside the partition + structure, and make it a partition after the data is loaded, checked, + and transformed. <programlisting> CREATE TABLE measurement_y2008m02 @@ -3455,9 +3912,73 @@ ALTER TABLE measurement_y2008m02 ADD CONSTRAINT y2008m02 ALTER TABLE measurement_y2008m02 INHERIT measurement; </programlisting> </para> - </sect2> + </sect3> - <sect2 id="ddl-partitioning-constraint-exclusion"> + <sect3 id="ddl-partitioning-inheritance-caveats"> + <title>Caveats</title> + + <para> + The following caveats apply to partitioned tables implemented using + inheritance: + <itemizedlist> + <listitem> + <para> + There is no automatic way to verify that all of the + <literal>CHECK</literal> constraints are mutually + exclusive. It is safer to create code that generates + partitions and creates and/or modifies associated objects than + to write each by hand. + </para> + </listitem> + + <listitem> + <para> + The schemes shown here assume that the partition key column(s) + of a row never change, or at least do not change enough to require + it to move to another partition. An <command>UPDATE</> that attempts + to do that will fail because of the <literal>CHECK</> constraints. + If you need to handle such cases, you can put suitable update triggers + on the partition tables, but it makes management of the structure + much more complicated. + </para> + </listitem> + + <listitem> + <para> + If you are using manual <command>VACUUM</command> or + <command>ANALYZE</command> commands, don't forget that + you need to run them on each partition individually. A command like: +<programlisting> +ANALYZE measurement; +</programlisting> + will only process the master table. + </para> + </listitem> + + <listitem> + <para> + <command>INSERT</command> statements with <literal>ON CONFLICT</> + clauses are unlikely to work as expected, as the <literal>ON CONFLICT</> + action is only taken in case of unique violations on the specified + target relation, not its child relations. + </para> + </listitem> + + <listitem> + <para> + Triggers or rules will be needed to route rows to the desired + partition, unless the application is explicitly aware of the + partitioning scheme. Triggers may be complicated to write, and will + be much slower than the tuple routing performed internally by + declarative partitioning. + </para> + </listitem> + </itemizedlist> + </para> + </sect3> + </sect2> + + <sect2 id="ddl-partitioning-constraint-exclusion"> <title>Partitioning and Constraint Exclusion</title> <indexterm> @@ -3467,7 +3988,8 @@ ALTER TABLE measurement_y2008m02 INHERIT measurement; <para> <firstterm>Constraint exclusion</> is a query optimization technique that improves performance for partitioned tables defined in the - fashion described above. As an example: + fashion described above (both declaratively partitioned tables and those + implemented using inheritance). As an example: <programlisting> SET constraint_exclusion = on; @@ -3550,124 +4072,9 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01'; are unlikely to benefit. </para> - </sect2> - - <sect2 id="ddl-partitioning-alternatives"> - <title>Alternative Partitioning Methods</title> - - <para> - A different approach to redirecting inserts into the appropriate - partition table is to set up rules, instead of a trigger, on the - master table. For example: - -<programlisting> -CREATE RULE measurement_insert_y2006m02 AS -ON INSERT TO measurement WHERE - ( logdate >= DATE '2006-02-01' AND logdate < DATE '2006-03-01' ) -DO INSTEAD - INSERT INTO measurement_y2006m02 VALUES (NEW.*); -... -CREATE RULE measurement_insert_y2008m01 AS -ON INSERT TO measurement WHERE - ( logdate >= DATE '2008-01-01' AND logdate < DATE '2008-02-01' ) -DO INSTEAD - INSERT INTO measurement_y2008m01 VALUES (NEW.*); -</programlisting> - - A rule has significantly more overhead than a trigger, but the overhead - is paid once per query rather than once per row, so this method might be - advantageous for bulk-insert situations. In most cases, however, the - trigger method will offer better performance. - </para> - - <para> - Be aware that <command>COPY</> ignores rules. If you want to - use <command>COPY</> to insert data, you'll need to copy into the correct - partition table rather than into the master. <command>COPY</> does fire - triggers, so you can use it normally if you use the trigger approach. - </para> - - <para> - Another disadvantage of the rule approach is that there is no simple - way to force an error if the set of rules doesn't cover the insertion - date; the data will silently go into the master table instead. - </para> - - <para> - Partitioning can also be arranged using a <literal>UNION ALL</literal> - view, instead of table inheritance. For example, - -<programlisting> -CREATE VIEW measurement AS - SELECT * FROM measurement_y2006m02 -UNION ALL SELECT * FROM measurement_y2006m03 -... -UNION ALL SELECT * FROM measurement_y2007m11 -UNION ALL SELECT * FROM measurement_y2007m12 -UNION ALL SELECT * FROM measurement_y2008m01; -</programlisting> - - However, the need to recreate the view adds an extra step to adding and - dropping individual partitions of the data set. In practice this - method has little to recommend it compared to using inheritance. - </para> - - </sect2> - - <sect2 id="ddl-partitioning-caveats"> - <title>Caveats</title> - - <para> - The following caveats apply to partitioned tables: - <itemizedlist> - <listitem> - <para> - There is no automatic way to verify that all of the - <literal>CHECK</literal> constraints are mutually - exclusive. It is safer to create code that generates - partitions and creates and/or modifies associated objects than - to write each by hand. - </para> - </listitem> - - <listitem> - <para> - The schemes shown here assume that the partition key column(s) - of a row never change, or at least do not change enough to require - it to move to another partition. An <command>UPDATE</> that attempts - to do that will fail because of the <literal>CHECK</> constraints. - If you need to handle such cases, you can put suitable update triggers - on the partition tables, but it makes management of the structure - much more complicated. - </para> - </listitem> - - <listitem> - <para> - If you are using manual <command>VACUUM</command> or - <command>ANALYZE</command> commands, don't forget that - you need to run them on each partition individually. A command like: -<programlisting> -ANALYZE measurement; -</programlisting> - will only process the master table. - </para> - </listitem> - - <listitem> - <para> - <command>INSERT</command> statements with <literal>ON CONFLICT</> - clauses are unlikely to work as expected, as the <literal>ON CONFLICT</> - action is only taken in case of unique violations on the specified - target relation, not its child relations. - </para> - </listitem> - - </itemizedlist> - </para> - <para> - The following caveats apply to constraint exclusion: + The following caveats apply to constraint exclusion, which is used by + both inheritance and partitioned tables: <itemizedlist> <listitem> @@ -3689,7 +4096,11 @@ ANALYZE measurement; range tests for range partitioning, as illustrated in the preceding examples. A good rule of thumb is that partitioning constraints should contain only comparisons of the partitioning column(s) to constants - using B-tree-indexable operators. + using B-tree-indexable operators, which applies even to partitioned + tables, because only B-tree-indexable column(s) are allowed in the + partition key. (This is not a problem when using declarative + partitioning, since the automatically generated constraints are simple + enough to be understood by the planner.) </para> </listitem> diff --git a/doc/src/sgml/dfunc.sgml b/doc/src/sgml/dfunc.sgml index 5a368f6df0..6a4b7d6e97 100644 --- a/doc/src/sgml/dfunc.sgml +++ b/doc/src/sgml/dfunc.sgml @@ -127,8 +127,8 @@ cc -shared -o foo.so foo.o <varlistentry> <term> - <systemitem class="osname">OS X</> - <indexterm><primary>OS X</><secondary>shared library</></> + <systemitem class="osname">macOS</> + <indexterm><primary>macOS</><secondary>shared library</></> </term> <listitem> <para> @@ -205,32 +205,6 @@ gcc -G -o foo.so foo.o </listitem> </varlistentry> - <varlistentry> - <term> - <systemitem class="osname">UnixWare</> - <indexterm><primary>UnixWare</><secondary>shared library</></> - </term> - <listitem> - <para> - The compiler flag to create <acronym>PIC</acronym> is <option>-K - PIC</option> with the SCO compiler and <option>-fpic</option> - with <productname>GCC</productname>. To link shared libraries, - the compiler option is <option>-G</option> with the SCO compiler - and <option>-shared</option> with - <productname>GCC</productname>. -<programlisting> -cc -K PIC -c foo.c -cc -G -o foo.so foo.o -</programlisting> - or -<programlisting> -gcc -fpic -c foo.c -gcc -shared -o foo.so foo.o -</programlisting> - </para> - </listitem> - </varlistentry> - </variablelist> <tip> diff --git a/doc/src/sgml/dml.sgml b/doc/src/sgml/dml.sgml index 8ee5cc08b8..60879e66b2 100644 --- a/doc/src/sgml/dml.sgml +++ b/doc/src/sgml/dml.sgml @@ -3,10 +3,6 @@ <chapter id="dml"> <title>Data Manipulation</title> - <remark> - This chapter is still quite incomplete. - </remark> - <para> The previous chapter discussed how to create tables and other structures to hold your data. Now it is time to fill the tables @@ -102,6 +98,18 @@ INSERT INTO products (product_no, name, price) VALUES </programlisting> </para> + <para> + It is also possible to insert the result of a query (which might be no + rows, one row, or many rows): +<programlisting> +INSERT INTO products (product_no, name, price) + SELECT product_no, name, price FROM new_products + WHERE release_date = 'today'; +</programlisting> + This provides the full power of the SQL query mechanism (<xref + linkend="queries">) for computing the rows to be inserted. + </para> + <tip> <para> When inserting a lot of data at the same time, considering using @@ -256,4 +264,91 @@ DELETE FROM products; then all rows in the table will be deleted! Caveat programmer. </para> </sect1> + + <sect1 id="dml-returning"> + <title>Returning Data From Modified Rows</title> + + <indexterm zone="dml-returning"> + <primary>RETURNING</primary> + </indexterm> + + <indexterm zone="dml-returning"> + <primary>INSERT</primary> + <secondary>RETURNING</secondary> + </indexterm> + + <indexterm zone="dml-returning"> + <primary>UPDATE</primary> + <secondary>RETURNING</secondary> + </indexterm> + + <indexterm zone="dml-returning"> + <primary>DELETE</primary> + <secondary>RETURNING</secondary> + </indexterm> + + <para> + Sometimes it is useful to obtain data from modified rows while they are + being manipulated. The <command>INSERT</>, <command>UPDATE</>, + and <command>DELETE</> commands all have an + optional <literal>RETURNING</> clause that supports this. Use + of <literal>RETURNING</> avoids performing an extra database query to + collect the data, and is especially valuable when it would otherwise be + difficult to identify the modified rows reliably. + </para> + + <para> + The allowed contents of a <literal>RETURNING</> clause are the same as + a <command>SELECT</> command's output list + (see <xref linkend="queries-select-lists">). It can contain column + names of the command's target table, or value expressions using those + columns. A common shorthand is <literal>RETURNING *</>, which selects + all columns of the target table in order. + </para> + + <para> + In an <command>INSERT</>, the data available to <literal>RETURNING</> is + the row as it was inserted. This is not so useful in trivial inserts, + since it would just repeat the data provided by the client. But it can + be very handy when relying on computed default values. For example, + when using a <link linkend="datatype-serial"><type>serial</></link> + column to provide unique identifiers, <literal>RETURNING</> can return + the ID assigned to a new row: +<programlisting> +CREATE TABLE users (firstname text, lastname text, id serial primary key); + +INSERT INTO users (firstname, lastname) VALUES ('Joe', 'Cool') RETURNING id; +</programlisting> + The <literal>RETURNING</> clause is also very useful + with <literal>INSERT ... SELECT</>. + </para> + + <para> + In an <command>UPDATE</>, the data available to <literal>RETURNING</> is + the new content of the modified row. For example: +<programlisting> +UPDATE products SET price = price * 1.10 + WHERE price <= 99.99 + RETURNING name, price AS new_price; +</programlisting> + </para> + + <para> + In a <command>DELETE</>, the data available to <literal>RETURNING</> is + the content of the deleted row. For example: +<programlisting> +DELETE FROM products + WHERE obsoletion_date = 'today' + RETURNING *; +</programlisting> + </para> + + <para> + If there are triggers (<xref linkend="triggers">) on the target table, + the data available to <literal>RETURNING</> is the row as modified by + the triggers. Thus, inspecting columns computed by triggers is another + common use-case for <literal>RETURNING</>. + </para> + + </sect1> </chapter> diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 6f896b565f..e8a9778822 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -20,7 +20,7 @@ </listitem> <listitem> <para> - PDF or PostScript, for printing + PDF, for printing </para> </listitem> <listitem> @@ -37,8 +37,8 @@ <para> <acronym>HTML</acronym> documentation and man pages are part of a - standard distribution and are installed by default. PDF and - PostScript format documentation is available separately for + standard distribution and are installed by default. PDF + format documentation is available separately for download. </para> @@ -55,6 +55,15 @@ used, but technically they are not interchangeable. </para> + <note> + <para> + The PostgreSQL documentation is currently being transitioned from DocBook + SGML and DSSSL style sheets to DocBook XML and XSLT style sheets. Be + careful to look at the instructions relating to the PostgreSQL version you + are dealing with, as the procedures and required tools will change. + </para> + </note> + <para> <productname>DocBook</productname> allows an author to specify the structure and content of a technical document without worrying @@ -86,11 +95,11 @@ <term><ulink url="http://www.oasis-open.org/docbook/">DocBook DTD</ulink></term> <listitem> <para> - This is the definition of DocBook itself. We currently use - version 4.2; you cannot use later or earlier versions. You - need the <acronym>SGML</acronym> variant of the DocBook DTD, - but to build man pages you also need the <acronym>XML</acronym> - variant of the same version. + This is the definition of DocBook itself. We currently use version + 4.2; you cannot use later or earlier versions. You need + the <acronym>SGML</acronym> and the <acronym>XML</acronym> variant of + the DocBook DTD of the same version. These will usually be in separate + packages. </para> </listitem> </varlistentry> @@ -99,51 +108,35 @@ <term><ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879 character entities</ulink></term> <listitem> <para> - These are required by DocBook but are distributed separately + These are required by DocBook SGML but are distributed separately because they are maintained by ISO. </para> </listitem> </varlistentry> <varlistentry> - <term><ulink url="http://wiki.docbook.org/DocBookDssslStylesheetDocs">DocBook DSSSL Stylesheets</ulink></term> + <term><ulink url="http://wiki.docbook.org/DocBookXslStylesheets">DocBook XSL Stylesheets</ulink></term> <listitem> <para> These contain the processing instructions for converting the DocBook sources to other formats, such as <acronym>HTML</acronym>. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><ulink url="http://wiki.docbook.org/DocBookXslStylesheets">DocBook XSL Stylesheets</ulink></term> - <listitem> - <para> - This is another stylesheet for converting DocBook to other - formats. We currently use this to produce man pages and - optionally HTMLHelp. You can also use this toolchain to - produce HTML or PDF output, but official PostgreSQL releases - use the DSSSL stylesheets for that. - </para> <para> - The minimum required version is currently 1.74.0. + The minimum required version is currently 1.77.0, but it is recommended + to use the latest available version for best results. </para> </listitem> </varlistentry> <varlistentry> - <term><ulink url="http://openjade.sourceforge.net">OpenJade</ulink></term> + <term><ulink url="http://openjade.sourceforge.net">OpenSP</ulink></term> <listitem> <para> - This is the base package of <acronym>SGML</acronym> processing. - It contains an <acronym>SGML</acronym> parser, a - <acronym>DSSSL</acronym> processor (that is, a program to - convert <acronym>SGML</acronym> to other formats using - <acronym>DSSSL</acronym> stylesheets), as well as a number of - related tools. <productname>Jade</productname> is now being - maintained by the OpenJade group, no longer by James Clark. + This is the base package of <acronym>SGML</acronym> processing. Note + that we no longer need OpenJade, the <acronym>DSSSL</acronym> + processor, only the OpenSP package for converting SGML to XML. </para> </listitem> </varlistentry> @@ -166,31 +159,17 @@ <term><ulink url="http://xmlsoft.org/XSLT/">Libxslt</ulink> for <command>xsltproc</command></term> <listitem> <para> - This is the processing tool to use with the XSLT stylesheets - (like <command>jade</command> is the processing tool for DSSSL - stylesheets). + <command>xsltproc</command> is an XSLT processor, that is, a program to + convert XML to other formats using XSLT stylesheets. </para> </listitem> </varlistentry> <varlistentry> - <term><ulink url="http://jadetex.sourceforge.net">JadeTeX</ulink></term> + <term><ulink url="https://xmlgraphics.apache.org/fop/">FOP</ulink></term> <listitem> <para> - If you want to, you can also install - <productname>JadeTeX</productname> to use - <productname>TeX</productname> as a formatting backend for - <productname>Jade</productname>. - <application>JadeTeX</application> can create PostScript or - <acronym>PDF</acronym> files (the latter with bookmarks). - </para> - - <para> - However, the output from <application>JadeTeX</application> is - inferior to what you get from the <acronym>RTF</acronym> - backend. Particular problem areas are tables and various - artifacts of vertical and horizontal spacing. Also, there is - no opportunity to manually polish the results. + This is a program for converting, among other things, XML to PDF. </para> </listitem> </varlistentry> @@ -206,13 +185,23 @@ here. </para> + <para> + You can get away with not installing DocBook XML and the DocBook XSLT + stylesheets locally, because the required files will be downloaded from the + Internet and cached locally. This may in fact be the preferred solution if + your operating system packages provide only an old version of especially + the stylesheets or if no packages are available at all. See + the <option>--nonet</option> option for <command>xmllint</command> + and <command>xsltproc</command> for more information. + </para> + <sect2> <title>Installation on Fedora, RHEL, and Derivatives</title> <para> To install the required packages, use: <programlisting> -yum install docbook-dtds docbook-style-dsssl docbook-style-xsl libxslt openjade +yum install docbook-dtds docbook-style-xsl fop libxslt opensp </programlisting> </para> </sect2> @@ -243,15 +232,25 @@ yum install docbook-dtds docbook-style-dsssl docbook-style-xsl libxslt openjade <para><filename>textproc/libxslt</filename></para> </listitem> <listitem> - <para><filename>textproc/openjade</filename></para> + <para><filename>textproc/fop</filename></para> + </listitem> + <listitem> + <para><filename>textproc/opensp</filename></para> </listitem> </itemizedlist> </para> <para> - A number of things from <filename>/usr/ports/print</filename> - (<filename>tex</filename>, <filename>jadetex</filename>) might - also be of interest. + To install the required packages with <command>pkg</command>, use: +<programlisting> +pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp +</programlisting> + </para> + + <para> + When building the documentation from the <filename>doc</filename> + directory you'll need to use <command>gmake</command>, because the + makefile provided is not suitable for FreeBSD's <command>make</command>. </para> <para> @@ -269,18 +268,18 @@ yum install docbook-dtds docbook-style-dsssl docbook-style-xsl libxslt openjade available for <productname>Debian GNU/Linux</productname>. To install, simply use: <programlisting> -apt-get install docbook docbook-dsssl docbook-xsl libxml2-utils openjade1.3 opensp xsltproc +apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc </programlisting> </para> </sect2> <sect2> - <title>OS X</title> + <title>macOS</title> <para> If you use MacPorts, the following will get you set up: <programlisting> -sudo port install docbook-dsssl docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl libxslt openjade opensp +sudo port install docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl fop libxslt opensp </programlisting> </para> </sect2> @@ -298,73 +297,24 @@ sudo port install docbook-dsssl docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl lib </para> <sect3> - <title>Installing OpenJade</title> + <title>Installing OpenSP</title> - <procedure> - <step> - <para> - The installation of OpenJade offers a GNU-style - <literal>./configure; make; make install</literal> build - process. Details can be found in the OpenJade source - distribution. In a nutshell: + <para> + The installation of OpenSP offers a GNU-style + <literal>./configure; make; make install</literal> build process. + Details can be found in the OpenSP source distribution. In a nutshell: <synopsis> -./configure --enable-default-catalog=/usr/local/share/sgml/catalog +./configure --enable-default-catalog=/usr/local/etc/sgml/catalog make make install </synopsis> - Be sure to remember where you put the <quote>default - catalog</quote>; you will need it below. You can also leave - it off, but then you will have to set the environment variable - <envar>SGML_CATALOG_FILES</envar> to point to the file - whenever you use <application>jade</application> later on. - (This method is also an option if OpenJade is already - installed and you want to install the rest of the toolchain - locally.) - </para> - - <note> - <para> - Some users have reported encountering a segmentation fault using - OpenJade 1.4devel to build the PDFs, with a message like: -<screen> -openjade:./stylesheet.dsl:664:2:E: flow object not accepted by port; only display flow objects accepted -make: *** [postgres-A4.tex-pdf] Segmentation fault -</screen> - Downgrading to OpenJade 1.3 should get rid of this error. - </para> - </note> - - </step> - - <step id="doc-openjade-install"> - <para> - Additionally, you should install the files - <filename>dsssl.dtd</filename>, <filename>fot.dtd</filename>, - <filename>style-sheet.dtd</filename>, and - <filename>catalog</filename> from the - <filename>dsssl</filename> directory somewhere, perhaps into - <filename>/usr/local/share/sgml/dsssl</filename>. It's - probably easiest to copy the entire directory: -<synopsis> -cp -R dsssl /usr/local/share/sgml -</synopsis> - </para> - </step> - - <step> - <para> - Finally, create the file - <filename>/usr/local/share/sgml/catalog</filename> and add - this line to it: -<programlisting> -CATALOG "dsssl/catalog" -</programlisting> - (This is a relative path reference to the file installed in - <xref linkend="doc-openjade-install">. Be sure to adjust it - if you chose your installation layout differently.) - </para> - </step> - </procedure> + Be sure to remember where you put the <quote>default catalog</quote>; you + will need it below. You can also leave it off, but then you will have to + set the environment variable <envar>SGML_CATALOG_FILES</envar> to point + to the file whenever you use any programs from OpenSP later on. (This + method is also an option if OpenSP is already installed and you want to + install the rest of the toolchain locally.) + </para> </sect3> <sect3> @@ -438,88 +388,6 @@ perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat </step> </procedure> </sect3> - - <sect3> - <title>Installing the DocBook <acronym>DSSSL</acronym> Style Sheets</title> - - <para> - To install the style sheets, unzip and untar the distribution and - move it to a suitable place, for example - <filename>/usr/local/share/sgml</filename>. (The archive will - automatically create a subdirectory.) -<screen> -<prompt>$</prompt> <userinput>gunzip docbook-dsssl-1.<replaceable>xx</>.tar.gz</userinput> -<prompt>$</prompt> <userinput>tar -C /usr/local/share/sgml -xf docbook-dsssl-1.<replaceable>xx</>.tar</userinput> -</screen> - </para> - - <para> - The usual catalog entry in - <filename>/usr/local/share/sgml/catalog</filename> can also be - made: -<programlisting> -CATALOG "docbook-dsssl-1.<replaceable>xx</>/catalog" -</programlisting> - Because stylesheets change rather often, and it's sometimes - beneficial to try out alternative versions, - <productname>PostgreSQL</productname> doesn't use this catalog - entry. See <xref linkend="docguide-toolsets-configure"> for - information about how to select the stylesheets instead. - </para> - </sect3> - - <sect3> - <title>Installing <productname>JadeTeX</productname></title> - - <para> - To install and use <productname>JadeTeX</productname>, you will - need a working installation of <productname>TeX</productname> and - <productname>LaTeX2e</productname>, including the supported - <productname>tools</productname> and - <productname>graphics</productname> packages, - <productname>Babel</productname>, - <productname><acronym>AMS</acronym> fonts</productname> and - <productname>AMS-LaTeX</productname>, the - <productname><acronym>PSNFSS</acronym></productname> extension - and companion kit of <quote>the 35 fonts</quote>, the - <productname>dvips</productname> program for generating - <productname>PostScript</productname>, the macro packages - <productname>fancyhdr</productname>, - <productname>hyperref</productname>, - <productname>minitoc</productname>, - <productname>url</productname> and - <productname>ot2enc</productname>. All of these can be found on - your friendly neighborhood <ulink url="http://www.ctan.org"> - <acronym>CTAN</acronym> site</ulink>. - The installation of the <application>TeX</application> base - system is far beyond the scope of this introduction. Binary - packages should be available for any system that can run - <application>TeX</application>. - </para> - - <para> - Before you can use <application>JadeTeX</application> with the - <productname>PostgreSQL</productname> documentation sources, you - will need to increase the size of - <application>TeX</application>'s internal data structures. - Details on this can be found in the <application>JadeTeX</application> - installation instructions. - </para> - - <para> - Once that is finished you can install <application>JadeTeX</application>: -<screen> -<prompt>$</prompt> <userinput>gunzip jadetex-<replaceable>xxx</replaceable>.tar.gz</userinput> -<prompt>$</prompt> <userinput>tar xf jadetex-<replaceable>xxx</replaceable>.tar</userinput> -<prompt>$</prompt> <userinput>cd jadetex</userinput> -<prompt>$</prompt> <userinput>make install</userinput> -<prompt>$</prompt> <userinput>mktexlsr</userinput> -</screen> - The last two need to be done as <systemitem>root</systemitem>. - </para> - - </sect3> - </sect2> <sect2 id="docguide-toolsets-configure"> @@ -534,28 +402,24 @@ CATALOG "docbook-dsssl-1.<replaceable>xx</>/catalog" <screen> <computeroutput> checking for onsgmls... onsgmls -checking for openjade... openjade checking for DocBook V4.2... yes -checking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modular -checking for collateindex.pl... /usr/bin/collateindex.pl +checking for dbtoepub... dbtoepub +checking for xmllint... xmllint checking for xsltproc... xsltproc checking for osx... osx +checking for fop... fop </computeroutput> </screen> If neither <filename>onsgmls</filename> nor <filename>nsgmls</filename> were found then some of the following tests - will be skipped. <filename>nsgmls</filename> is part of the Jade - package. You can pass the environment variables - <envar>JADE</envar> and <envar>NSGMLS</envar> to configure to point + will be skipped. <filename>nsgmls</filename> is part of the OpenSP + package. You can pass the environment variable + <envar>NSGMLS</envar> to configure to point to the programs if they are not found automatically. If <quote>DocBook V4.2</quote> was not found then you did not install - the DocBook DTD kit in a place where Jade can find it, or you have + the DocBook DTD kit in a place where OpenSP can find it, or you have not set up the catalog files correctly. See the installation hints - above. The DocBook stylesheets are looked for in a number of - relatively standard places, but if you have them some other place - then you should set the environment variable - <envar>DOCBOOKSTYLE</envar> to the location and rerun - <filename>configure</filename> afterwards. + above. </para> </sect2> @@ -585,28 +449,12 @@ checking for osx... osx <para> To produce HTML documentation with the stylesheet used on <ulink - url="http://postgresql.org/docs/current">postgresql.org</> instead of the + url="https://www.postgresql.org/docs/current">postgresql.org</> instead of the default simple style use: <screen> <prompt>doc/src/sgml$ </prompt><userinput>make STYLE=website html</userinput> </screen> </para> - - <para> - To create a proper index, the build might process several identical - stages. If you do not care about the index, and just want to - proof-read the output, use <literal>draft</>: -<screen> -<prompt>doc/src/sgml$ </prompt><userinput>make draft</userinput> -</screen> - </para> - - <para> - To build the documentation as a single HTML page, use: -<screen> -<prompt>doc/src/sgml$ </prompt><userinput>make postgres.html</userinput> -</screen> - </para> </sect2> <sect2> @@ -619,328 +467,66 @@ checking for osx... osx pages. The man pages are also distributed as a tar archive, similar to the <acronym>HTML</acronym> version. To create the man pages, use the commands: -<programlisting> -cd doc/src/sgml -make man -</programlisting> +<screen> +<prompt>doc/src/sgml$ </prompt><userinput>make man</userinput> +</screen> </para> </sect2> <sect2> - <title>Print Output via <application>JadeTeX</application></title> + <title>PDF</title> <para> - If you want to use <application>JadeTex</application> to produce a - printable rendition of the documentation, you can use one of the - following commands: + To produce a PDF rendition of the documentation + using <productname>FOP</productname>, you can use one of the following + commands, depending on the preferred paper format: <itemizedlist> <listitem> <para> - To generate PostScript via <acronym>DVI</acronym> in A4 format: -<screen> -<prompt>doc/src/sgml$ </prompt><userinput>make postgres-A4.ps</userinput> -</screen> - In U.S. letter format: + For A4 format: <screen> -<prompt>doc/src/sgml$ </prompt><userinput>make postgres-US.ps</userinput> +<prompt>doc/src/sgml$ </prompt><userinput>make postgres-A4.pdf</userinput> </screen> </para> </listitem> <listitem> <para> - To make a <acronym>PDF</acronym>: -<screen> -<prompt>doc/src/sgml$ </prompt><userinput>make postgres-A4.pdf</userinput> -</screen> - or: + For U.S. letter format: <screen> <prompt>doc/src/sgml$ </prompt><userinput>make postgres-US.pdf</userinput> </screen> - (Of course you can also make a <acronym>PDF</acronym> version - from the PostScript, but if you generate <acronym>PDF</acronym> - directly, it will have hyperlinks and other enhanced features.) </para> </listitem> </itemizedlist> </para> <para> - When using JadeTeX to build the PostgreSQL documentation, you will - probably need to increase some of TeX's internal parameters. These - can be set in the file <filename>texmf.cnf</filename>. The following - settings worked at the time of this writing: + Because the PostgreSQL documentation is fairly + big, <productname>FOP</productname> will require a significant amount of + memory. Because of that, on some systems, the build will fail with a + memory-related error message. This can usually be fixed by configuring + Java heap settings in the configuration + file <filename>~/.foprc</filename>, for example: <programlisting> -hash_extra.jadetex = 200000 -hash_extra.pdfjadetex = 200000 -pool_size.jadetex = 2000000 -pool_size.pdfjadetex = 2000000 -string_vacancies.jadetex = 150000 -string_vacancies.pdfjadetex = 150000 -max_strings.jadetex = 300000 -max_strings.pdfjadetex = 300000 -save_size.jadetex = 15000 -save_size.pdfjadetex = 15000 +# FOP binary distribution +FOP_OPTS='-Xmx1000m' +# Debian +JAVA_ARGS='-Xmx1000m' +# Red Hat +ADDITIONAL_FLAGS='-Xmx1000m' </programlisting> + There is a minimum amount of memory that is required, and to some extent + more memory appears to make things a bit faster. On systems with very + little memory (less than 1 GB), the build will either be very slow due to + swapping or will not work at all. </para> - </sect2> - - <sect2> - <title>Overflow Text</title> - - <para> - Occasionally text is too wide for the printed margins, and in - extreme cases, too wide for the printed page, e.g. non-wrapped - text, wide tables. Overly wide text generates <quote>Overfull - hbox</quote> messages in the TeX log output file, e.g. - <filename>postgres-US.log</> or <filename>postgres-A4.log</>. - There are 72 points in an inch so anything reported as over 72 - points too wide will probably not fit on the printed page (assuming - one inch margins). To find the <acronym>SGML</acronym> text - causing the overflow, find the first page number mentioned above - the overflow message, e.g. <literal>[50 ###]</> (page 50), and - look at the page after that (e.g. page 51) in the <acronym>PDF</acronym> - file to see the overflow text and adjust the <acronym>SGML</acronym> - accordingly. - </para> - </sect2> - - <sect2> - <title>Print Output via <acronym>RTF</acronym></title> - <para> - You can also create a printable version of the <productname>PostgreSQL</productname> - documentation by converting it to <acronym>RTF</acronym> and - applying minor formatting corrections using an office suite. - Depending on the capabilities of the particular office suite, you - can then convert the documentation to PostScript of - <acronym>PDF</acronym>. The procedure below illustrates this - process using <productname>Applixware</productname>. + Other XSL-FO processors can also be used manually, but the automated build + process only supports FOP. </para> - - <note> - <para> - It appears that current versions of the <productname>PostgreSQL</productname> documentation - trigger some bug in or exceed the size limit of OpenJade. If the - build process of the <acronym>RTF</acronym> version hangs for a - long time and the output file still has size 0, then you might have - hit that problem. (But keep in mind that a normal build takes 5 - to 10 minutes, so don't abort too soon.) - </para> - </note> - - <procedure> - <title><productname>Applixware</productname> <acronym>RTF</acronym> Cleanup</title> - - <para> - <application>OpenJade</application> omits specifying a default - style for body text. In the past, this undiagnosed problem led to - a long process of table of contents generation. However, with - great help from the <productname>Applixware</productname> folks - the symptom was diagnosed and a workaround is available. - </para> - - <step performance="required"> - <para> - Generate the <acronym>RTF</acronym> version by typing: -<screen> -<prompt>doc/src/sgml$ </prompt><userinput>make postgres.rtf</userinput> -</screen> - </para> - </step> - - <step performance="required"> - <para> - Repair the RTF file to correctly specify all styles, in - particular the default style. If the document contains - <sgmltag>refentry</sgmltag> sections, one must also replace - formatting hints which tie a preceding paragraph to the current - paragraph, and instead tie the current paragraph to the - following one. A utility, <command>fixrtf</command>, is - available in <filename>doc/src/sgml</filename> to accomplish - these repairs: -<screen> -<prompt>doc/src/sgml$ </prompt><userinput>./fixrtf --refentry postgres.rtf</userinput> -</screen> - </para> - - <para> - The script adds <literal>{\s0 Normal;}</literal> as the zeroth - style in the document. According to - <productname>Applixware</productname>, the RTF standard would - prohibit adding an implicit zeroth style, though Microsoft Word - happens to handle this case. For repairing - <sgmltag>refentry</sgmltag> sections, the script replaces - <literal>\keepn</literal> tags with <literal>\keep</literal>. - </para> - </step> - - <step performance="required"> - <para> - Open a new document in <productname>Applixware Words</productname> and - then import the <acronym>RTF</acronym> file. - </para> - </step> - - <step performance="required"> - <para> - Generate a new table of contents (ToC) using - <productname>Applixware</productname>. - </para> - - <substeps> - <step> - <para> - Select the existing ToC lines, from the beginning of the first - character on the first line to the last character of the last - line. - </para> - </step> - - <step> - <para> - Build a new ToC using - <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book - Building</guisubmenu><guimenuitem>Create Table of - Contents</guimenuitem></menuchoice>. Select the first three - levels of headers for inclusion in the ToC. This will replace - the existing lines imported in the RTF with a native - <productname>Applixware</productname> ToC. - </para> - </step> - - <step> - <para> - Adjust the ToC formatting by using - <menuchoice><guimenu>Format</guimenu><guimenuitem>Style</guimenuitem></menuchoice>, - selecting each of the three ToC styles, and adjusting the - indents for <literal>First</literal> and - <literal>Left</literal>. Use the following values: - - <informaltable> - <tgroup cols="3"> - <thead> - <row> - <entry>Style</entry> - <entry>First Indent (inches)</entry> - <entry>Left Indent (inches)</entry> - </row> - </thead> - - <tbody> - <row> - <entry><literal>TOC-Heading 1</literal></entry> - <entry><literal>0.4</literal></entry> - <entry><literal>0.4</literal></entry> - </row> - - <row> - <entry><literal>TOC-Heading 2</literal></entry> - <entry><literal>0.8</literal></entry> - <entry><literal>0.8</literal></entry> - </row> - - <row> - <entry><literal>TOC-Heading 3</literal></entry> - <entry><literal>1.2</literal></entry> - <entry><literal>1.2</literal></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </step> - </substeps> - </step> - - <step performance="required"> - <para> - Work through the document to: - - <itemizedlist> - <listitem> - <para> - Adjust page breaks. - </para> - </listitem> - - <listitem> - <para> - Adjust table column widths. - </para> - </listitem> - </itemizedlist> - </para> - </step> - - <step performance="required"> - <para> - Replace the right-justified page numbers in the Examples and - Figures portions of the ToC with correct values. This only takes - a few minutes. - </para> - </step> - - <step performance="optional"> - <para> - Delete the index section from the document if it is empty. - </para> - </step> - - <step performance="required"> - <para> - Regenerate and adjust the table of contents. - </para> - - <substeps> - <step> - <para> - Select the ToC field. - </para> - </step> - - <step> - <para> - Select <menuchoice><guimenu>Tools</guimenu><guisubmenu>Book - Building</guisubmenu><guimenuitem>Create Table of - Contents</guimenuitem></menuchoice>. - </para> - </step> - - <step> - <para> - Unbind the ToC by selecting - <menuchoice><guimenu>Tools</guimenu><guisubmenu>Field - Editing</guisubmenu><guimenuitem>Unprotect</guimenuitem></menuchoice>. - </para> - </step> - - <step> - <para> - Delete the first line in the ToC, which is an entry for the - ToC itself. - </para> - </step> - </substeps> - </step> - - <step performance="required"> - <para> - Save the document as native <productname>Applixware - Words</productname> format to allow easier last minute editing - later. - </para> - </step> - - <step performance="required"> - <para> - <quote>Print</quote> the document - to a file in PostScript format. - </para> - </step> - </procedure> </sect2> <sect2> diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml index a30e25cfa0..dead4c3f86 100644 --- a/doc/src/sgml/ecpg.sgml +++ b/doc/src/sgml/ecpg.sgml @@ -508,6 +508,33 @@ EXEC SQL COMMIT; </varlistentry> <varlistentry> + <term><literal>EXEC SQL PREPARE TRANSACTION </literal><replaceable class="PARAMETER">transaction_id</></term> + <listitem> + <para> + Prepare the current transaction for two-phase commit. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>EXEC SQL COMMIT PREPARED </literal><replaceable class="PARAMETER">transaction_id</></term> + <listitem> + <para> + Commit a transaction that is in prepared state. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>EXEC SQL ROLLBACK PREPARED </literal><replaceable class="PARAMETER">transaction_id</></term> + <listitem> + <para> + Roll back a transaction that is in prepared state. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><literal>EXEC SQL SET AUTOCOMMIT TO ON</literal></term> <listitem> <para> @@ -517,7 +544,7 @@ EXEC SQL COMMIT; </varlistentry> <varlistentry> - <term><literal>SET AUTOCOMMIT TO OFF</literal></term> + <term><literal>EXEC SQL SET AUTOCOMMIT TO OFF</literal></term> <listitem> <para> Disable autocommit mode. This is the default. @@ -892,6 +919,11 @@ do <entry><type>boolean</type></entry> <entry><type>bool</type><footnote><para>declared in <filename>ecpglib.h</filename> if not native</para></footnote></entry> </row> + + <row> + <entry><type>bytea</type></entry> + <entry><type>char *</type></entry> + </row> </tbody> </tgroup> </table> @@ -1162,7 +1194,7 @@ EXEC SQL END DECLARE SECTION; There are two use cases for arrays as host variables. The first is a way to store some text string in <type>char[]</type> or <type>VARCHAR[]</type>, as - explained <xref linkend="ecpg-char">. The second use case is to + explained in <xref linkend="ecpg-char">. The second use case is to retrieve multiple rows from a query result without using a cursor. Without an array, to process a query result consisting of multiple rows, it is required to use a cursor and @@ -3565,7 +3597,7 @@ void PGTYPESdecimal_free(decimal *var); EXEC SQL ALLOCATE DESCRIPTOR <replaceable>identifier</replaceable>; </programlisting> The identifier serves as the <quote>variable name</quote> of the - descriptor area. <remark>The scope of the allocated descriptor is WHAT?.</remark> + descriptor area. <!-- The scope of the allocated descriptor is WHAT?. --> When you don't need the descriptor anymore, you should deallocate it: <programlisting> diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml index f050ff1f66..c4f211bc02 100644 --- a/doc/src/sgml/extend.sgml +++ b/doc/src/sgml/extend.sgml @@ -335,11 +335,13 @@ by <application>pg_dump</>. Such a change is usually only sensible if you concurrently make the same change in the extension's script file. (But there are special provisions for tables containing configuration - data; see below.) + data; see <xref linkend="extend-extensions-config-tables">.) + In production situations, it's generally better to create an extension + update script to perform changes to extension member objects. </para> <para> - The extension script may set privileges on objects which are part of the + The extension script may set privileges on objects that are part of the extension via <command>GRANT</command> and <command>REVOKE</command> statements. The final set of privileges for each object (if any are set) will be stored in the @@ -388,6 +390,15 @@ schema(s) its member objects are within. </para> + <para> + If an extension's script creates any temporary objects (such as temp + tables), those objects are treated as extension members for the + remainder of the current session, but are automatically dropped at + session end, as any temporary object would be. This is an exception + to the rule that extension member objects cannot be dropped without + dropping the whole extension. + </para> + <sect2> <title>Extension Files</title> @@ -453,9 +464,11 @@ <term><varname>comment</varname> (<type>string</type>)</term> <listitem> <para> - A comment (any string) about the extension. Alternatively, - the comment can be set by means of the <xref linkend="sql-comment"> - command in the script file. + A comment (any string) about the extension. The comment is applied + when initially creating an extension, but not during extension updates + (since that might override user-added comments). Alternatively, + the extension's comment can be set by writing + a <xref linkend="sql-comment"> command in the script file. </para> </listitem> </varlistentry> @@ -518,7 +531,7 @@ its contained objects into a different schema after initial creation of the extension. The default is <literal>false</>, i.e. the extension is not relocatable. - See below for more information. + See <xref linkend="extend-extensions-relocation"> for more information. </para> </listitem> </varlistentry> @@ -529,7 +542,10 @@ <para> This parameter can only be set for non-relocatable extensions. It forces the extension to be loaded into exactly the named schema - and not any other. See below for more information. + and not any other. + The <varname>schema</varname> parameter is consulted only when + initially creating an extension, not during extension updates. + See <xref linkend="extend-extensions-relocation"> for more information. </para> </listitem> </varlistentry> @@ -562,7 +578,8 @@ comments) by the extension mechanism. This provision is commonly used to throw an error if the script file is fed to <application>psql</> rather than being loaded via <command>CREATE EXTENSION</> (see example - script below). Without that, users might accidentally load the + script in <xref linkend="extend-extensions-example">). + Without that, users might accidentally load the extension's contents as <quote>loose</> objects rather than as an extension, a state of affairs that's a bit tedious to recover from. </para> @@ -580,7 +597,7 @@ </sect2> - <sect2> + <sect2 id="extend-extensions-relocation"> <title>Extension Relocatability</title> <para> @@ -678,7 +695,7 @@ SET LOCAL search_path TO @extschema@; </para> </sect2> - <sect2> + <sect2 id="extend-extensions-config-tables"> <title>Extension Configuration Tables</title> <para> @@ -762,7 +779,7 @@ SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entr out but the dump will not be able to be restored directly and user intervention will be required. </para> - + <para> Sequences associated with <type>serial</> or <type>bigserial</> columns need to be directly marked to dump their state. Marking their parent @@ -795,7 +812,8 @@ SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entr environment that <command>CREATE EXTENSION</> provides for installation scripts: in particular, <varname>search_path</> is set up in the same way, and any new objects created by the script are automatically added - to the extension. + to the extension. Also, if the script chooses to drop extension member + objects, they are automatically dissociated from the extension. </para> <para> @@ -878,6 +896,47 @@ SELECT * FROM pg_extension_update_paths('<replaceable>extension_name</>'); </sect2> <sect2> + <title>Installing Extensions using Update Scripts</title> + + <para> + An extension that has been around for awhile will probably exist in + several versions, for which the author will need to write update scripts. + For example, if you have released a <literal>foo</> extension in + versions <literal>1.0</>, <literal>1.1</>, and <literal>1.2</>, there + should be update scripts <filename>foo--1.0--1.1.sql</> + and <filename>foo--1.1--1.2.sql</>. + Before <productname>PostgreSQL</> 10, it was necessary to also create + new script files <filename>foo--1.1.sql</> and <filename>foo--1.2.sql</> + that directly build the newer extension versions, or else the newer + versions could not be installed directly, only by + installing <literal>1.0</> and then updating. That was tedious and + duplicative, but now it's unnecessary, because <command>CREATE + EXTENSION</> can follow update chains automatically. + For example, if only the script + files <filename>foo--1.0.sql</>, <filename>foo--1.0--1.1.sql</>, + and <filename>foo--1.1--1.2.sql</> are available then a request to + install version <literal>1.2</> is honored by running those three + scripts in sequence. The processing is the same as if you'd first + installed <literal>1.0</> and then updated to <literal>1.2</>. + (As with <command>ALTER EXTENSION UPDATE</>, if multiple pathways are + available then the shortest is preferred.) Arranging an extension's + script files in this style can reduce the amount of maintenance effort + needed to produce small updates. + </para> + + <para> + If you use secondary (version-specific) control files with an extension + maintained in this style, keep in mind that each version needs a control + file even if it has no stand-alone installation script, as that control + file will determine how the implicit update to that version is performed. + For example, if <filename>foo--1.0.control</> specifies <literal>requires + = 'bar'</> but <literal>foo</>'s other control files do not, the + extension's dependency on <literal>bar</> will be dropped when updating + from <literal>1.0</> to another version. + </para> + </sect2> + + <sect2 id="extend-extensions-example"> <title>Extension Example</title> <para> @@ -1145,6 +1204,15 @@ include $(PGXS) </varlistentry> <varlistentry> + <term><varname>NO_INSTALLCHECK</varname></term> + <listitem> + <para> + don't define an installcheck target, useful e.g. if tests require special configuration, or don't use pg_regress + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>EXTRA_CLEAN</varname></term> <listitem> <para> diff --git a/doc/src/sgml/external-projects.sgml b/doc/src/sgml/external-projects.sgml index 88094c19ea..8457426545 100644 --- a/doc/src/sgml/external-projects.sgml +++ b/doc/src/sgml/external-projects.sgml @@ -72,7 +72,7 @@ <entry>JDBC</entry> <entry>JDBC</entry> <entry>Type 4 JDBC driver</entry> - <entry><ulink url="http://jdbc.postgresql.org/"></ulink></entry> + <entry><ulink url="https://jdbc.postgresql.org/"></ulink></entry> </row> <row> @@ -190,7 +190,7 @@ <row> <entry>PL/R</entry> <entry>R</entry> - <entry><ulink url="http://www.joeconway.com/plr/"></ulink></entry> + <entry><ulink url="http://www.joeconway.com/plr.html"></ulink></entry> </row> <row> diff --git a/doc/src/sgml/fdwhandler.sgml b/doc/src/sgml/fdwhandler.sgml index 0c1db070ed..dbeaab555d 100644 --- a/doc/src/sgml/fdwhandler.sgml +++ b/doc/src/sgml/fdwhandler.sgml @@ -1254,6 +1254,20 @@ InitializeWorkerForeignScan(ForeignScanState *node, shm_toc *toc, This callback is optional, and needs only be supplied if this custom path supports parallel execution. </para> + + <para> +<programlisting> +void +ShutdownForeignScan(ForeignScanState *node); +</programlisting> + Release resources when it is anticipated the node will not be executed + to completion. This is not called in all cases; sometimes, + <literal>EndForeignScan</> may be called without this function having + been called first. Since the DSM segment used by parallel query is + destroyed just after this callback is invoked, foreign data wrappers that + wish to take some action before the DSM segment goes away should implement + this method. + </para> </sect2> </sect1> diff --git a/doc/src/sgml/file-fdw.sgml b/doc/src/sgml/file-fdw.sgml index d3b39aa120..74941a6f1e 100644 --- a/doc/src/sgml/file-fdw.sgml +++ b/doc/src/sgml/file-fdw.sgml @@ -10,10 +10,11 @@ <para> The <filename>file_fdw</> module provides the foreign-data wrapper <function>file_fdw</function>, which can be used to access data - files in the server's file system. Data files must be in a format + files in the server's file system, or to execute programs on the server + and read their output. The data file or program output must be in a format that can be read by <command>COPY FROM</command>; see <xref linkend="sql-copy"> for details. - Access to such data files is currently read-only. + Access to data files is currently read-only. </para> <para> @@ -27,7 +28,22 @@ <listitem> <para> - Specifies the file to be read. Required. Must be an absolute path name. + Specifies the file to be read. Must be an absolute path name. + Either <literal>filename</literal> or <literal>program</literal> must be + specified, but not both. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>program</literal></term> + + <listitem> + <para> + Specifies the command to be executed. The standard output of this + command will be read as though <command>COPY FROM PROGRAM</> were used. + Either <literal>program</literal> or <literal>filename</literal> must be + specified, but not both. </para> </listitem> </varlistentry> @@ -37,7 +53,7 @@ <listitem> <para> - Specifies the file's format, + Specifies the data format, the same as <command>COPY</>'s <literal>FORMAT</literal> option. </para> </listitem> @@ -48,7 +64,7 @@ <listitem> <para> - Specifies whether the file has a header line, + Specifies whether the data has a header line, the same as <command>COPY</>'s <literal>HEADER</literal> option. </para> </listitem> @@ -59,7 +75,7 @@ <listitem> <para> - Specifies the file's delimiter character, + Specifies the data delimiter character, the same as <command>COPY</>'s <literal>DELIMITER</literal> option. </para> </listitem> @@ -70,7 +86,7 @@ <listitem> <para> - Specifies the file's quote character, + Specifies the data quote character, the same as <command>COPY</>'s <literal>QUOTE</literal> option. </para> </listitem> @@ -81,7 +97,7 @@ <listitem> <para> - Specifies the file's escape character, + Specifies the data escape character, the same as <command>COPY</>'s <literal>ESCAPE</literal> option. </para> </listitem> @@ -92,7 +108,7 @@ <listitem> <para> - Specifies the file's null string, + Specifies the data null string, the same as <command>COPY</>'s <literal>NULL</literal> option. </para> </listitem> @@ -103,7 +119,7 @@ <listitem> <para> - Specifies the file's encoding, + Specifies the data encoding, the same as <command>COPY</>'s <literal>ENCODING</literal> option. </para> </listitem> @@ -112,11 +128,11 @@ </variablelist> <para> - Note that while <command>COPY</> allows options such as OIDS and HEADER - to be specified without a corresponding value, the foreign data wrapper + Note that while <command>COPY</> allows options such as <literal>HEADER</> + to be specified without a corresponding value, the foreign table option syntax requires a value to be present in all cases. To activate - <command>COPY</> options normally supplied without a value, you can - instead pass the value TRUE. + <command>COPY</> options typically written without a value, you can pass + the value TRUE, since all such options are Booleans. </para> <para> @@ -133,7 +149,7 @@ <para> This is a Boolean option. If true, it specifies that values of the column should not be matched against the null string (that is, the - file-level <literal>null</literal> option). This has the same effect + table-level <literal>null</literal> option). This has the same effect as listing the column in <command>COPY</>'s <literal>FORCE_NOT_NULL</literal> option. </para> @@ -171,14 +187,24 @@ <para> Changing table-level options requires superuser privileges, for security - reasons: only a superuser should be able to determine which file is read. - In principle non-superusers could be allowed to change the other options, - but that's not supported at present. + reasons: only a superuser should be able to control which file is read + or which program is run. In principle non-superusers could be allowed to + change the other options, but that's not supported at present. + </para> + + <para> + When specifying the <literal>program</> option, keep in mind that the option + string is executed by the shell. If you need to pass any arguments to the + command that come from an untrusted source, you must be careful to strip or + escape any characters that might have special meaning to the shell. + For security reasons, it is best to use a fixed command string, or at least + avoid passing any user input in it. </para> <para> For a foreign table using <literal>file_fdw</>, <command>EXPLAIN</> shows - the name of the file to be read. Unless <literal>COSTS OFF</> is + the name of the file to be read or program to be run. + For a file, unless <literal>COSTS OFF</> is specified, the file size (in bytes) is shown as well. </para> @@ -186,7 +212,7 @@ <title id="csvlog-fdw">Create a Foreign Table for PostgreSQL CSV Logs</title> <para> - One of the obvious uses for the <literal>file_fdw</> is to make + One of the obvious uses for <literal>file_fdw</> is to make the PostgreSQL activity log available as a table for querying. To do this, first you must be logging to a CSV file, which here we will call <literal>pglog.csv</>. First, install <literal>file_fdw</> @@ -236,7 +262,7 @@ CREATE FOREIGN TABLE pglog ( location text, application_name text ) SERVER pglog -OPTIONS ( filename '/home/josh/9.1/data/pg_log/pglog.csv', format 'csv' ); +OPTIONS ( filename '/home/josh/data/log/pglog.csv', format 'csv' ); </programlisting> </para> diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index eba6689088..37bddc7f4e 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -12,9 +12,6 @@ <!ENTITY query SYSTEM "query.sgml"> <!ENTITY start SYSTEM "start.sgml"> -<!-- currently unused, but contains some interesting information --> -<!ENTITY sql SYSTEM "sql.sgml"> - <!-- user's guide --> <!ENTITY array SYSTEM "array.sgml"> <!ENTITY datatype SYSTEM "datatype.sgml"> @@ -24,6 +21,7 @@ <!ENTITY indices SYSTEM "indices.sgml"> <!ENTITY json SYSTEM "json.sgml"> <!ENTITY mvcc SYSTEM "mvcc.sgml"> +<!ENTITY parallel SYSTEM "parallel.sgml"> <!ENTITY perform SYSTEM "perform.sgml"> <!ENTITY queries SYSTEM "queries.sgml"> <!ENTITY rangetypes SYSTEM "rangetypes.sgml"> @@ -51,6 +49,7 @@ <!ENTITY wal SYSTEM "wal.sgml"> <!ENTITY add-node SYSTEM "add-node.sgml"> <!ENTITY remove-node SYSTEM "remove-node.sgml"> +<!ENTITY logical-replication SYSTEM "logical-replication.sgml"> <!-- programmer's guide --> <!ENTITY bgworker SYSTEM "bgworker.sgml"> @@ -107,6 +106,7 @@ <!-- contrib information --> <!ENTITY contrib SYSTEM "contrib.sgml"> <!ENTITY adminpack SYSTEM "adminpack.sgml"> +<!ENTITY amcheck SYSTEM "amcheck.sgml"> <!ENTITY auth-delay SYSTEM "auth-delay.sgml"> <!ENTITY auto-explain SYSTEM "auto-explain.sgml"> <!ENTITY bloom SYSTEM "bloom.sgml"> @@ -155,7 +155,6 @@ <!ENTITY test-decoding SYSTEM "test-decoding.sgml"> <!ENTITY test-parser SYSTEM "test-parser.sgml"> <!ENTITY test-shm-mq SYSTEM "test-shm-mq.sgml"> -<!ENTITY tsearch2 SYSTEM "tsearch2.sgml"> <!ENTITY tsm-system-rows SYSTEM "tsm-system-rows.sgml"> <!ENTITY tsm-system-time SYSTEM "tsm-system-time.sgml"> <!ENTITY unaccent SYSTEM "unaccent.sgml"> @@ -173,6 +172,7 @@ <!ENTITY sourcerepo SYSTEM "sourcerepo.sgml"> <!ENTITY release SYSTEM "release.sgml"> +<!ENTITY release-10 SYSTEM "release-10.sgml"> <!ENTITY release-9.6 SYSTEM "release-9.6.sgml"> <!ENTITY release-xl-9.5r1 SYSTEM "release-xl-9.5r1.sgml"> <!ENTITY release-9.5 SYSTEM "release-9.5.sgml"> @@ -198,7 +198,6 @@ <!-- back matter --> <!ENTITY biblio SYSTEM "biblio.sgml"> -<!ENTITY bookindex SYSTEM "bookindex.sgml"> <!-- Some parts of the documentation are also source for some plain-text @@ -208,14 +207,3 @@ --> <!ENTITY % standalone-ignore "INCLUDE"> <!ENTITY % standalone-include "IGNORE"> - -<!-- - By default, no index is included. Use -i include-index on the command line - to include it. - --> -<!ENTITY % include-index "IGNORE"> - -<!-- - Create empty index element for processing by XSLT stylesheet. - --> -<!ENTITY % include-xslt-index "IGNORE"> diff --git a/doc/src/sgml/fixrtf b/doc/src/sgml/fixrtf deleted file mode 100755 index 31cb5f85c0..0000000000 --- a/doc/src/sgml/fixrtf +++ /dev/null @@ -1,46 +0,0 @@ -#!/bin/sh -# fixrtf - -# doc/src/sgml/fixrtf - -# Repair (slightly) damaged RTF generated by jade -# Applixware wants the s0 stylesheet defined, whereas -# M$Word does not care about it. -# (c) 2001, Thomas Lockhart, PostgreSQL Inc. - -flist="" -RPAT="" -for i in $@ ; do - case "$i" in - -r|--refentry) - RPAT='-e s/\\\keepn/\\\keep/g' - ;; - -?|--help) - echo "$0 [--refentry] <rtf file> ..." - exit 0 - ;; - -*) - echo "Command $i not recognized" - $0 --help - exit 1 - ;; - *) - flist="$flist $i" - esac -done - -if [ "$flist" = "" ] ; then - flist=*.rtf -fi - -for f in $flist ; do - echo -n "Repairing '$f' ..." - if [ -r $f ] ; then - (sed -e 's/{\\stylesheet{\\s1/{\\stylesheet{\\s0 Normal 0;}{\\s1/g' $RPAT $f > $f.new \ - && mv -f $f.new $f \ - && echo " done") || echo " failed" - else - echo " file not found" - fi -done -exit diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 22f52ce256..7c5cbab2a2 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -996,7 +996,7 @@ </indexterm> <literal><function>scale(<type>numeric</type>)</function></literal> </entry> - <entry><type>numeric</type></entry> + <entry><type>integer</type></entry> <entry>scale of the argument (the number of decimal digits in the fractional part)</entry> <entry><literal>scale(8.41)</literal></entry> <entry><literal>2</literal></entry> @@ -1534,11 +1534,12 @@ </entry> <entry><type>text</type></entry> <entry> - Remove the longest string containing only the + Remove the longest string containing only characters from <parameter>characters</parameter> (a space by default) from the - start/end/both ends of the <parameter>string</parameter> + start, end, or both ends (<literal>both</> is the default) + of <parameter>string</parameter> </entry> - <entry><literal>trim(both 'x' from 'xTomxx')</literal></entry> + <entry><literal>trim(both 'xyz' from 'yxTomxx')</literal></entry> <entry><literal>Tom</literal></entry> </row> @@ -1547,14 +1548,14 @@ <literal><function>trim(<optional>leading | trailing | both</optional> <optional>from</optional> <parameter>string</parameter> - <optional><parameter>, characters</parameter></optional> + <optional>, <parameter>characters</parameter></optional> )</function></literal> </entry> <entry><type>text</type></entry> <entry> - Non-standard version of <function>trim()</> + Non-standard syntax for <function>trim()</> </entry> - <entry><literal>trim(both from 'xTomxx', 'x')</literal></entry> + <entry><literal>trim(both from 'yxTomxx', 'xyz')</literal></entry> <entry><literal>Tom</literal></entry> </row> @@ -1626,7 +1627,7 @@ in <parameter>characters</parameter> (a space by default) from the start and end of <parameter>string</parameter> </entry> - <entry><literal>btrim('xyxtrimyyx', 'xy')</literal></entry> + <entry><literal>btrim('xyxtrimyyx', 'xyz')</literal></entry> <entry><literal>trim</literal></entry> </row> @@ -1895,8 +1896,8 @@ <parameter>characters</parameter> (a space by default) from the start of <parameter>string</parameter> </entry> - <entry><literal>ltrim('zzzytrim', 'xyz')</literal></entry> - <entry><literal>trim</literal></entry> + <entry><literal>ltrim('zzzytest', 'xyz')</literal></entry> + <entry><literal>test</literal></entry> </row> <row> @@ -2039,18 +2040,35 @@ <row> <entry> <indexterm> + <primary>regexp_match</primary> + </indexterm> + <literal><function>regexp_match(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> [, <parameter>flags</parameter> <type>text</type>])</function></literal> + </entry> + <entry><type>text[]</type></entry> + <entry> + Return captured substring(s) resulting from the first match of a POSIX + regular expression to the <parameter>string</parameter>. See + <xref linkend="functions-posix-regexp"> for more information. + </entry> + <entry><literal>regexp_match('foobarbequebaz', '(bar)(beque)')</literal></entry> + <entry><literal>{bar,beque}</literal></entry> + </row> + + <row> + <entry> + <indexterm> <primary>regexp_matches</primary> </indexterm> <literal><function>regexp_matches(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> [, <parameter>flags</parameter> <type>text</type>])</function></literal> </entry> <entry><type>setof text[]</type></entry> <entry> - Return all captured substrings resulting from matching a POSIX regular - expression against the <parameter>string</parameter>. See + Return captured substring(s) resulting from matching a POSIX regular + expression to the <parameter>string</parameter>. See <xref linkend="functions-posix-regexp"> for more information. </entry> - <entry><literal>regexp_matches('foobarbequebaz', '(bar)(beque)')</literal></entry> - <entry><literal>{bar,beque}</literal></entry> + <entry><literal>regexp_matches('foobarbequebaz', 'ba.', 'g')</literal></entry> + <entry><literal>{bar}</literal><para><literal>{baz}</literal></para> (2 rows)</entry> </row> <row> @@ -2201,8 +2219,8 @@ <parameter>characters</parameter> (a space by default) from the end of <parameter>string</parameter> </entry> - <entry><literal>rtrim('trimxxxx', 'x')</literal></entry> - <entry><literal>trim</literal></entry> + <entry><literal>rtrim('testxxzx', 'xyz')</literal></entry> + <entry><literal>test</literal></entry> </row> <row> @@ -3467,11 +3485,11 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); </entry> <entry><type>bytea</type></entry> <entry> - Remove the longest string containing only the bytes in + Remove the longest string containing only bytes appearing in <parameter>bytes</parameter> from the start and end of <parameter>string</parameter> </entry> - <entry><literal>trim(E'\\000'::bytea from E'\\000Tom\\000'::bytea)</literal></entry> + <entry><literal>trim(E'\\000\\001'::bytea from E'\\000Tom\\001'::bytea)</literal></entry> <entry><literal>Tom</literal></entry> </row> </tbody> @@ -3510,11 +3528,11 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); </entry> <entry><type>bytea</type></entry> <entry> - Remove the longest string consisting only of bytes - in <parameter>bytes</parameter> from the start and end of + Remove the longest string containing only bytes appearing in + <parameter>bytes</parameter> from the start and end of <parameter>string</parameter> </entry> - <entry><literal>btrim(E'\\000trim\\000'::bytea, E'\\000'::bytea)</literal></entry> + <entry><literal>btrim(E'\\000trim\\001'::bytea, E'\\000\\001'::bytea)</literal></entry> <entry><literal>trim</literal></entry> </row> @@ -4113,6 +4131,9 @@ substring('foobar' from '#"o_b#"%' for '#') <lineannotation>NULL</lineannotat <primary>regexp_replace</primary> </indexterm> <indexterm> + <primary>regexp_match</primary> + </indexterm> + <indexterm> <primary>regexp_matches</primary> </indexterm> <indexterm> @@ -4272,64 +4293,106 @@ regexp_replace('foobarbaz', 'b(..)', E'X\\1Y', 'g') </para> <para> - The <function>regexp_matches</> function returns a text array of - all of the captured substrings resulting from matching a POSIX - regular expression pattern. It has the syntax - <function>regexp_matches</function>(<replaceable>string</>, <replaceable>pattern</> - <optional>, <replaceable>flags</> </optional>). - The function can return no rows, one row, or multiple rows (see - the <literal>g</> flag below). If the <replaceable>pattern</> - does not match, the function returns no rows. If the pattern - contains no parenthesized subexpressions, then each row - returned is a single-element text array containing the substring - matching the whole pattern. If the pattern contains parenthesized - subexpressions, the function returns a text array whose - <replaceable>n</>'th element is the substring matching the - <replaceable>n</>'th parenthesized subexpression of the pattern - (not counting <quote>non-capturing</> parentheses; see below for - details). - The <replaceable>flags</> parameter is an optional text - string containing zero or more single-letter flags that change the - function's behavior. Flag <literal>g</> causes the function to find - each match in the string, not only the first one, and return a row for - each such match. Supported flags (though - not <literal>g</>) - are described in <xref linkend="posix-embedded-options-table">. + The <function>regexp_match</> function returns a text array of + captured substring(s) resulting from the first match of a POSIX + regular expression pattern to a string. It has the syntax + <function>regexp_match</function>(<replaceable>string</>, + <replaceable>pattern</> <optional>, <replaceable>flags</> </optional>). + If there is no match, the result is <literal>NULL</>. + If a match is found, and the <replaceable>pattern</> contains no + parenthesized subexpressions, then the result is a single-element text + array containing the substring matching the whole pattern. + If a match is found, and the <replaceable>pattern</> contains + parenthesized subexpressions, then the result is a text array + whose <replaceable>n</>'th element is the substring matching + the <replaceable>n</>'th parenthesized subexpression of + the <replaceable>pattern</> (not counting <quote>non-capturing</> + parentheses; see below for details). + The <replaceable>flags</> parameter is an optional text string + containing zero or more single-letter flags that change the function's + behavior. Supported flags are described + in <xref linkend="posix-embedded-options-table">. </para> <para> Some examples: <programlisting> -SELECT regexp_matches('foobarbequebaz', '(bar)(beque)'); - regexp_matches ----------------- +SELECT regexp_match('foobarbequebaz', 'bar.*que'); + regexp_match +-------------- + {barbeque} +(1 row) + +SELECT regexp_match('foobarbequebaz', '(bar)(beque)'); + regexp_match +-------------- {bar,beque} (1 row) +</programlisting> + In the common case where you just want the whole matching substring + or <literal>NULL</> for no match, write something like +<programlisting> +SELECT (regexp_match('foobarbequebaz', 'bar.*que'))[1]; + regexp_match +-------------- + barbeque +(1 row) +</programlisting> + </para> + + <para> + The <function>regexp_matches</> function returns a set of text arrays + of captured substring(s) resulting from matching a POSIX regular + expression pattern to a string. It has the same syntax as + <function>regexp_match</function>. + This function returns no rows if there is no match, one row if there is + a match and the <literal>g</> flag is not given, or <replaceable>N</> + rows if there are <replaceable>N</> matches and the <literal>g</> flag + is given. Each returned row is a text array containing the whole + matched substring or the substrings matching parenthesized + subexpressions of the <replaceable>pattern</>, just as described above + for <function>regexp_match</function>. + <function>regexp_matches</> accepts all the flags shown + in <xref linkend="posix-embedded-options-table">, plus + the <literal>g</> flag which commands it to return all matches, not + just the first one. + </para> + + <para> + Some examples: +<programlisting> + SELECT regexp_matches('foo', 'not there'); + regexp_matches +---------------- +(0 rows) SELECT regexp_matches('foobarbequebazilbarfbonk', '(b[^b]+)(b[^b]+)', 'g'); - regexp_matches + regexp_matches ---------------- {bar,beque} {bazil,barf} (2 rows) - -SELECT regexp_matches('foobarbequebaz', 'barbeque'); - regexp_matches ----------------- - {barbeque} -(1 row) </programlisting> </para> - <para> - It is possible to force <function>regexp_matches()</> to always - return one row by using a sub-select; this is particularly useful - in a <literal>SELECT</> target list when you want all rows - returned, even non-matching ones: + <tip> + <para> + In most cases <function>regexp_matches()</> should be used with + the <literal>g</> flag, since if you only want the first match, it's + easier and more efficient to use <function>regexp_match()</>. + However, <function>regexp_match()</> only exists + in <productname>PostgreSQL</> version 10 and up. When working in older + versions, a common trick is to place a <function>regexp_matches()</> + call in a sub-select, for example: <programlisting> SELECT col1, (SELECT regexp_matches(col2, '(bar)(beque)')) FROM tab; </programlisting> - </para> + This produces a text array if there's a match, or <literal>NULL</> if + not, the same as <function>regexp_match()</> would do. Without the + sub-select, this query would produce no output at all for table rows + without a match, which is typically not the desired behavior. + </para> + </tip> <para> The <function>regexp_split_to_table</> function splits a string using a POSIX @@ -4408,6 +4471,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; zero-length matches that occur at the start or end of the string or immediately after a previous match. This is contrary to the strict definition of regexp matching that is implemented by + <function>regexp_match</> and <function>regexp_matches</>, but is usually the most convenient behavior in practice. Other software systems such as Perl use similar definitions. </para> @@ -5482,7 +5546,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); into the digits and the parts before and after them. We might try to do that like this: <screen> -SELECT regexp_matches('abc01234xyz', '(.*)(\d+)(.*)'); +SELECT regexp_match('abc01234xyz', '(.*)(\d+)(.*)'); <lineannotation>Result: </lineannotation><computeroutput>{abc0123,4,xyz}</computeroutput> </screen> That didn't work: the first <literal>.*</> is greedy so @@ -5490,14 +5554,14 @@ SELECT regexp_matches('abc01234xyz', '(.*)(\d+)(.*)'); match at the last possible place, the last digit. We might try to fix that by making it non-greedy: <screen> -SELECT regexp_matches('abc01234xyz', '(.*?)(\d+)(.*)'); +SELECT regexp_match('abc01234xyz', '(.*?)(\d+)(.*)'); <lineannotation>Result: </lineannotation><computeroutput>{abc,0,""}</computeroutput> </screen> That didn't work either, because now the RE as a whole is non-greedy and so it ends the overall match as soon as possible. We can get what we want by forcing the RE as a whole to be greedy: <screen> -SELECT regexp_matches('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); +SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); <lineannotation>Result: </lineannotation><computeroutput>{abc,01234,xyz}</computeroutput> </screen> Controlling the RE's overall greediness separately from its components' @@ -5769,6 +5833,17 @@ SELECT regexp_matches('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); </para> </note> + <tip> + <para> + <function>to_timestamp</function> and <function>to_date</function> + exist to handle input formats that cannot be converted by + simple casting. For most standard date/time formats, simply casting the + source string to the required data type works, and is much easier. + Similarly, <function>to_number</> is unnecessary for standard numeric + representations. + </para> + </tip> + <para> In a <function>to_char</> output template string, there are certain patterns that are recognized and replaced with appropriately-formatted @@ -5975,7 +6050,7 @@ SELECT regexp_matches('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); </row> <row> <entry><literal>Q</literal></entry> - <entry>quarter (ignored by <function>to_date</> and <function>to_timestamp</>)</entry> + <entry>quarter</entry> </row> <row> <entry><literal>RM</literal></entry> @@ -5987,15 +6062,18 @@ SELECT regexp_matches('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); </row> <row> <entry><literal>TZ</literal></entry> - <entry>upper case time-zone name</entry> + <entry>upper case time-zone abbreviation + (only supported in <function>to_char</>)</entry> </row> <row> <entry><literal>tz</literal></entry> - <entry>lower case time-zone name</entry> + <entry>lower case time-zone abbreviation + (only supported in <function>to_char</>)</entry> </row> <row> <entry><literal>OF</literal></entry> - <entry>time-zone offset</entry> + <entry>time-zone offset from UTC + (only supported in <function>to_char</>)</entry> </row> </tbody> </tgroup> @@ -6095,20 +6173,6 @@ SELECT regexp_matches('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); <listitem> <para> - <function>to_timestamp</function> and <function>to_date</function> - exist to handle input formats that cannot be converted by - simple casting. These functions interpret input liberally, - with minimal error checking. While they produce valid output, - the conversion can yield unexpected results. For example, - input to these functions is not restricted by normal ranges, - thus <literal>to_date('20096040','YYYYMMDD')</literal> returns - <literal>2014-01-17</literal> rather than causing an error. - Casting does not have this behavior. - </para> - </listitem> - - <listitem> - <para> Ordinary text is allowed in <function>to_char</function> templates and will be output literally. You can put a substring in double quotes to force it to be interpreted as literal text @@ -6132,7 +6196,8 @@ SELECT regexp_matches('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); <listitem> <para> - If the year format specification is less than four digits, e.g. + In <function>to_timestamp</function> and <function>to_date</function>, + if the year format specification is less than four digits, e.g. <literal>YYY</>, and the supplied year is less than four digits, the year will be adjusted to be nearest to the year 2020, e.g. <literal>95</> becomes 1995. @@ -6141,8 +6206,9 @@ SELECT regexp_matches('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); <listitem> <para> - The <literal>YYYY</literal> conversion from string to <type>timestamp</type> or - <type>date</type> has a restriction when processing years with more than 4 digits. You must + In <function>to_timestamp</function> and <function>to_date</function>, + the <literal>YYYY</literal> conversion has a restriction when + processing years with more than 4 digits. You must use some non-digit character or template after <literal>YYYY</literal>, otherwise the year is always interpreted as 4 digits. For example (with the year 20000): @@ -6156,12 +6222,12 @@ SELECT regexp_matches('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); <listitem> <para> - In conversions from string to <type>timestamp</type> or - <type>date</type>, the <literal>CC</literal> (century) field is ignored + In <function>to_timestamp</function> and <function>to_date</function>, + the <literal>CC</literal> (century) field is accepted but ignored if there is a <literal>YYY</literal>, <literal>YYYY</literal> or <literal>Y,YYY</literal> field. If <literal>CC</literal> is used with - <literal>YY</literal> or <literal>Y</literal> then the year is computed - as the year in the specified century. If the century is + <literal>YY</literal> or <literal>Y</literal> then the result is + computed as that year in the specified century. If the century is specified but the year is not, the first year of the century is assumed. </para> @@ -6169,9 +6235,19 @@ SELECT regexp_matches('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); <listitem> <para> - An ISO 8601 week-numbering date (as distinct from a Gregorian date) - can be specified to <function>to_timestamp</function> and - <function>to_date</function> in one of two ways: + In <function>to_timestamp</function> and <function>to_date</function>, + weekday names or numbers (<literal>DAY</literal>, <literal>D</literal>, + and related field types) are accepted but are ignored for purposes of + computing the result. The same is true for quarter + (<literal>Q</literal>) fields. + </para> + </listitem> + + <listitem> + <para> + In <function>to_timestamp</function> and <function>to_date</function>, + an ISO 8601 week-numbering date (as distinct from a Gregorian date) + can be specified in one of two ways: <itemizedlist> <listitem> <para> @@ -6213,23 +6289,24 @@ SELECT regexp_matches('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); <listitem> <para> - In a conversion from string to <type>timestamp</type>, millisecond + In <function>to_timestamp</function>, millisecond (<literal>MS</literal>) or microsecond (<literal>US</literal>) - values are used as the + fields are used as the seconds digits after the decimal point. For example - <literal>to_timestamp('12:3', 'SS:MS')</literal> is not 3 milliseconds, - but 300, because the conversion counts it as 12 + 0.3 seconds. - This means for the format <literal>SS:MS</literal>, the input values - <literal>12:3</literal>, <literal>12:30</literal>, and <literal>12:300</literal> specify the - same number of milliseconds. To get three milliseconds, one must use - <literal>12:003</literal>, which the conversion counts as + <literal>to_timestamp('12.3', 'SS.MS')</literal> is not 3 milliseconds, + but 300, because the conversion treats it as 12 + 0.3 seconds. + So, for the format <literal>SS.MS</literal>, the input values + <literal>12.3</literal>, <literal>12.30</literal>, + and <literal>12.300</literal> specify the + same number of milliseconds. To get three milliseconds, one must write + <literal>12.003</literal>, which the conversion treats as 12 + 0.003 = 12.003 seconds. </para> <para> Here is a more complex example: - <literal>to_timestamp('15:12:02.020.001230', 'HH:MI:SS.MS.US')</literal> + <literal>to_timestamp('15:12:02.020.001230', 'HH24:MI:SS.MS.US')</literal> is 15 hours, 12 minutes, and 2 seconds + 20 milliseconds + 1230 microseconds = 2.021230 seconds. </para> @@ -6247,9 +6324,10 @@ SELECT regexp_matches('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); <listitem> <para> <function>to_char(interval)</function> formats <literal>HH</> and - <literal>HH12</> as shown on a 12-hour clock, i.e. zero hours - and 36 hours output as <literal>12</>, while <literal>HH24</> - outputs the full hour value, which can exceed 23 for intervals. + <literal>HH12</> as shown on a 12-hour clock, for example zero hours + and 36 hours both output as <literal>12</>, while <literal>HH24</> + outputs the full hour value, which can exceed 23 in + an <type>interval</> value. </para> </listitem> @@ -8302,12 +8380,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple <row> <entry> <literal>#</literal> </entry> <entry>Point or box of intersection</entry> - <entry><literal>'((1,-1),(-1,1))' # '((1,1),(-1,-1))'</literal></entry> + <entry><literal>box '((1,-1),(-1,1))' # box '((1,1),(-2,-2))'</literal></entry> </row> <row> <entry> <literal>#</literal> </entry> <entry>Number of points in path or polygon</entry> - <entry><literal># '((1,0),(0,1),(-1,0))'</literal></entry> + <entry><literal># path '((1,0),(0,1),(-1,0))'</literal></entry> </row> <row> <entry> <literal>@-@</literal> </entry> @@ -9150,6 +9228,62 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple for NOT, AND and OR. </para> + <para> + <xref linkend="macaddr8-functions-table"> shows the functions + available for use with the <type>macaddr8</type> type. The function + <literal><function>trunc(<type>macaddr8</type>)</function></literal> returns a MAC + address with the last 5 bytes set to zero. This can be used to + associate the remaining prefix with a manufacturer. + </para> + + <table id="macaddr8-functions-table"> + <title><type>macaddr8</type> Functions</title> + <tgroup cols="5"> + <thead> + <row> + <entry>Function</entry> + <entry>Return Type</entry> + <entry>Description</entry> + <entry>Example</entry> + <entry>Result</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <indexterm> + <primary>trunc</primary> + </indexterm> + <literal><function>trunc(<type>macaddr8</type>)</function></literal> + </entry> + <entry><type>macaddr8</type></entry> + <entry>set last 5 bytes to zero</entry> + <entry><literal>trunc(macaddr8 '12:34:56:78:90:ab:cd:ef')</literal></entry> + <entry><literal>12:34:56:00:00:00:00:00</literal></entry> + </row> + <row> + <entry> + <indexterm> + <primary>macaddr8_set7bit</primary> + </indexterm> + <literal><function>macaddr8_set7bit(<type>macaddr8</type>)</function></literal> + </entry> + <entry><type>macaddr8</type></entry> + <entry>set 7th bit to one, also known as modified EUI-64, for inclusion in an IPv6 address</entry> + <entry><literal>macaddr8_set7bit(macaddr8 '00:34:56:ab:cd:ef')</literal></entry> + <entry><literal>02:34:56:ff:fe:ab:cd:ef</literal></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + The <type>macaddr8</type> type also supports the standard relational + operators (<literal>></literal>, <literal><=</literal>, etc.) for + ordering, and the bitwise arithmetic operators (<literal>~</literal>, + <literal>&</literal> and <literal>|</literal>) for NOT, AND and OR. + </para> + </sect1> @@ -9432,6 +9566,18 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple </row> <row> <entry> + <literal><function>to_tsvector(<optional> <replaceable class="PARAMETER">config</> <type>regconfig</> , </optional> <replaceable class="PARAMETER">document</> <type>json(b)</type>)</function></literal> + </entry> + <entry><type>tsvector</type></entry> + <entry> + reduce each string value in the document to a <type>tsvector</>, and then + concatentate those in document order to produce a single <type>tsvector</> + </entry> + <entry><literal>to_tsvector('english', '{"a": "The Fat Rats"}'::json)</literal></entry> + <entry><literal>'fat':2 'rat':3</literal></entry> + </row> + <row> + <entry> <indexterm> <primary>ts_delete</primary> </indexterm> @@ -9460,7 +9606,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple <literal><function>ts_filter(<replaceable class="PARAMETER">vector</replaceable> <type>tsvector</>, <replaceable class="PARAMETER">weights</replaceable> <type>"char"[]</>)</function></literal> </entry> <entry><type>tsvector</type></entry> - <entry>Select only elements with given <replaceable class="PARAMETER">weights</replaceable> from <replaceable class="PARAMETER">vector</replaceable></entry> + <entry>select only elements with given <replaceable class="PARAMETER">weights</replaceable> from <replaceable class="PARAMETER">vector</replaceable></entry> <entry><literal>ts_filter('fat:2,4 cat:3b rat:5A'::tsvector, '{a,b}')</literal></entry> <entry><literal>'cat':3B 'rat':5A</literal></entry> </row> @@ -9478,6 +9624,15 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple </row> <row> <entry> + <literal><function>ts_headline(<optional> <replaceable class="PARAMETER">config</replaceable> <type>regconfig</>, </optional> <replaceable class="PARAMETER">document</replaceable> <type>json(b)</>, <replaceable class="PARAMETER">query</replaceable> <type>tsquery</> <optional>, <replaceable class="PARAMETER">options</replaceable> <type>text</> </optional>)</function></literal> + </entry> + <entry><type>text</type></entry> + <entry>display a query match</entry> + <entry><literal>ts_headline('{"a":"x y z"}'::json, 'z'::tsquery)</literal></entry> + <entry><literal>{"a":"x y <b>z</b>"}</literal></entry> + </row> + <row> + <entry> <indexterm> <primary>ts_rank</primary> </indexterm> @@ -9540,7 +9695,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple </entry> <entry><type>tsquery</type></entry> <entry>make query that searches for <replaceable>query1</> followed by - <replaceable>query2</> at maximum distance <replaceable>distance</></entry> + <replaceable>query2</> at distance <replaceable>distance</></entry> <entry><literal>tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10)</literal></entry> <entry><literal>'fat' <10> 'cat'</literal></entry> </row> @@ -10250,50 +10405,54 @@ SELECT xml_is_well_formed_document('<pg:foo xmlns:pg="http://postgresql.org/stuf <sect2 id="functions-xml-processing"> <title>Processing XML</title> - <indexterm> - <primary>XPath</primary> - </indexterm> - <para> To process values of data type <type>xml</type>, PostgreSQL offers the functions <function>xpath</function> and <function>xpath_exists</function>, which evaluate XPath 1.0 - expressions. + expressions, and the <function>XMLTABLE</function> + table function. </para> + <sect3 id="functions-xml-processing-xpath"> + <title><literal>xpath</literal></title> + + <indexterm> + <primary>XPath</primary> + </indexterm> + <synopsis> <function>xpath</function>(<replaceable>xpath</replaceable>, <replaceable>xml</replaceable> <optional>, <replaceable>nsarray</replaceable></optional>) </synopsis> - <para> - The function <function>xpath</function> evaluates the XPath - expression <replaceable>xpath</replaceable> (a <type>text</> value) - against the XML value - <replaceable>xml</replaceable>. It returns an array of XML values - corresponding to the node set produced by the XPath expression. - If the XPath expression returns a scalar value rather than a node set, - a single-element array is returned. - </para> + <para> + The function <function>xpath</function> evaluates the XPath + expression <replaceable>xpath</replaceable> (a <type>text</> value) + against the XML value + <replaceable>xml</replaceable>. It returns an array of XML values + corresponding to the node set produced by the XPath expression. + If the XPath expression returns a scalar value rather than a node set, + a single-element array is returned. + </para> - <para> - The second argument must be a well formed XML document. In particular, - it must have a single root node element. - </para> + <para> + The second argument must be a well formed XML document. In particular, + it must have a single root node element. + </para> - <para> - The optional third argument of the function is an array of namespace - mappings. This array should be a two-dimensional <type>text</> array with - the length of the second axis being equal to 2 (i.e., it should be an - array of arrays, each of which consists of exactly 2 elements). - The first element of each array entry is the namespace name (alias), the - second the namespace URI. It is not required that aliases provided in - this array be the same as those being used in the XML document itself (in - other words, both in the XML document and in the <function>xpath</function> - function context, aliases are <emphasis>local</>). - </para> + <para> + The optional third argument of the function is an array of namespace + mappings. This array should be a two-dimensional <type>text</> array with + the length of the second axis being equal to 2 (i.e., it should be an + array of arrays, each of which consists of exactly 2 elements). + The first element of each array entry is the namespace name (alias), the + second the namespace URI. It is not required that aliases provided in + this array be the same as those being used in the XML document itself (in + other words, both in the XML document and in the <function>xpath</function> + function context, aliases are <emphasis>local</>). + </para> - <para> - Example: + <para> + Example: <screen><![CDATA[ SELECT xpath('/my:a/text()', '<my:a xmlns:my="http://example.com">test</my:a>', ARRAY[ARRAY['my', 'http://example.com']]); @@ -10303,10 +10462,10 @@ SELECT xpath('/my:a/text()', '<my:a xmlns:my="http://example.com">test</my:a>', {test} (1 row) ]]></screen> - </para> + </para> - <para> - To deal with default (anonymous) namespaces, do something like this: + <para> + To deal with default (anonymous) namespaces, do something like this: <screen><![CDATA[ SELECT xpath('//mydefns:b/text()', '<a xmlns="http://example.com"><b>test</b></a>', ARRAY[ARRAY['mydefns', 'http://example.com']]); @@ -10316,27 +10475,31 @@ SELECT xpath('//mydefns:b/text()', '<a xmlns="http://example.com"><b>test</b></a {test} (1 row) ]]></screen> - </para> + </para> + </sect3> - <indexterm> - <primary>xpath_exists</primary> - </indexterm> + <sect3 id="functions-xml-processing-xpath-exists"> + <title><literal>xpath_exists</literal></title> + + <indexterm> + <primary>xpath_exists</primary> + </indexterm> <synopsis> <function>xpath_exists</function>(<replaceable>xpath</replaceable>, <replaceable>xml</replaceable> <optional>, <replaceable>nsarray</replaceable></optional>) </synopsis> - <para> - The function <function>xpath_exists</function> is a specialized form - of the <function>xpath</function> function. Instead of returning the - individual XML values that satisfy the XPath, this function returns a - Boolean indicating whether the query was satisfied or not. This - function is equivalent to the standard <literal>XMLEXISTS</> predicate, - except that it also offers support for a namespace mapping argument. - </para> + <para> + The function <function>xpath_exists</function> is a specialized form + of the <function>xpath</function> function. Instead of returning the + individual XML values that satisfy the XPath, this function returns a + Boolean indicating whether the query was satisfied or not. This + function is equivalent to the standard <literal>XMLEXISTS</> predicate, + except that it also offers support for a namespace mapping argument. + </para> - <para> - Example: + <para> + Example: <screen><![CDATA[ SELECT xpath_exists('/my:a/text()', '<my:a xmlns:my="http://example.com">test</my:a>', ARRAY[ARRAY['my', 'http://example.com']]); @@ -10346,7 +10509,238 @@ SELECT xpath_exists('/my:a/text()', '<my:a xmlns:my="http://example.com">test</m t (1 row) ]]></screen> - </para> + </para> + </sect3> + + <sect3 id="functions-xml-processing-xmltable"> + <title><literal>xmltable</literal></title> + + <indexterm> + <primary>xmltable</primary> + </indexterm> + + <indexterm zone="functions-xml-processing-xmltable"> + <primary>table function</primary> + <secondary>XMLTABLE</secondary> + </indexterm> + +<synopsis> +<function>xmltable</function>( <optional>XMLNAMESPACES(<replaceable>namespace uri</replaceable> AS <replaceable>namespace name</replaceable><optional>, ...</optional>), </optional> + <replaceable>row_expression</replaceable> PASSING <optional>BY REF</optional> <replaceable>document_expression</replaceable> <optional>BY REF</optional> + COLUMNS <replaceable>name</replaceable> { <replaceable>type</replaceable> <optional>PATH <replaceable>column_expression</replaceable></optional> <optional>DEFAULT <replaceable>default_expression</replaceable></optional> <optional>NOT NULL | NULL</optional> + | FOR ORDINALITY } + <optional>, ...</optional> +) +</synopsis> + + <para> + The <function>xmltable</function> function produces a table based + on the given XML value, an XPath filter to extract rows, and an + optional set of column definitions. + </para> + + <para> + The optional <literal>XMLNAMESPACES</> clause is a comma-separated + list of namespaces. It specifies the XML namespaces used in + the document and their aliases. A default namespace specification + is not currently supported. + </para> + + <para> + The required <replaceable>row_expression</> argument is an XPath + expression that is evaluated against the supplied XML document to + obtain an ordered sequence of XML nodes. This sequence is what + <function>xmltable</> transforms into output rows. + </para> + + <para> + <replaceable>document_expression</> provides the XML document to + operate on. + The <literal>BY REF</literal> clauses have no effect in PostgreSQL, + but are allowed for SQL conformance and compatibility with other + implementations. + The argument must be a well-formed XML document; fragments/forests + are not accepted. + </para> + + <para> + The mandatory <literal>COLUMNS</literal> clause specifies the list + of columns in the output table. + If the <literal>COLUMNS</> clause is omitted, the rows in the result + set contain a single column of type <literal>xml</> containing the + data matched by <replaceable>row_expression</>. + If <literal>COLUMNS</literal> is specified, each entry describes a + single column. + See the syntax summary above for the format. + The column name and type are required; the path, default and + nullability clauses are optional. + </para> + + <para> + A column marked <literal>FOR ORDINALITY</literal> will be populated + with row numbers matching the order in which the + output rows appeared in the original input XML document. + At most one column may be marked <literal>FOR ORDINALITY</literal>. + </para> + + <para> + The <literal>column_expression</> for a column is an XPath expression + that is evaluated for each row, relative to the result of the + <replaceable>row_expression</>, to find the value of the column. + If no <literal>column_expression</> is given, then the column name + is used as an implicit path. + </para> + + <para> + If a column's XPath expression returns multiple elements, an error + is raised. + If the expression matches an empty tag, the result is an + empty string (not <literal>NULL</>). + Any <literal>xsi:nil</> attributes are ignored. + </para> + + <para> + The text body of the XML matched by the <replaceable>column_expression</> + is used as the column value. Multiple <literal>text()</literal> nodes + within an element are concatenated in order. Any child elements, + processing instructions, and comments are ignored, but the text contents + of child elements are concatenated to the result. + Note that the whitespace-only <literal>text()</> node between two non-text + elements is preserved, and that leading whitespace on a <literal>text()</> + node is not flattened. + </para> + + <para> + If the path expression does not match for a given row but + <replaceable>default_expression</> is specified, the value resulting + from evaluating that expression is used. + If no <literal>DEFAULT</> clause is given for the column, + the field will be set to <literal>NULL</>. + It is possible for a <replaceable>default_expression</> to reference + the value of output columns that appear prior to it in the column list, + so the default of one column may be based on the value of another + column. + </para> + + <para> + Columns may be marked <literal>NOT NULL</>. If the + <replaceable>column_expression</> for a <literal>NOT NULL</> column + does not match anything and there is no <literal>DEFAULT</> or the + <replaceable>default_expression</> also evaluates to null, an error + is reported. + </para> + + <para> + Unlike regular PostgreSQL functions, <replaceable>column_expression</> + and <replaceable>default_expression</> are not evaluated to a simple + value before calling the function. + <replaceable>column_expression</> is normally evaluated + exactly once per input row, and <replaceable>default_expression</> + is evaluated each time a default is needed for a field. + If the expression qualifies as stable or immutable the repeat + evaluation may be skipped. + Effectively <function>xmltable</> behaves more like a subquery than a + function call. + This means that you can usefully use volatile functions like + <function>nextval</> in <replaceable>default_expression</>, and + <replaceable>column_expression</> may depend on other parts of the + XML document. + </para> + + <para> + Examples: + <screen><![CDATA[ +CREATE TABLE xmldata AS SELECT +xml $$ +<ROWS> + <ROW id="1"> + <COUNTRY_ID>AU</COUNTRY_ID> + <COUNTRY_NAME>Australia</COUNTRY_NAME> + </ROW> + <ROW id="5"> + <COUNTRY_ID>JP</COUNTRY_ID> + <COUNTRY_NAME>Japan</COUNTRY_NAME> + <PREMIER_NAME>Shinzo Abe</PREMIER_NAME> + <SIZE unit="sq_mi">145935</SIZE> + </ROW> + <ROW id="6"> + <COUNTRY_ID>SG</COUNTRY_ID> + <COUNTRY_NAME>Singapore</COUNTRY_NAME> + <SIZE unit="sq_km">697</SIZE> + </ROW> +</ROWS> +$$ AS data; + +SELECT xmltable.* + FROM xmldata, + XMLTABLE('//ROWS/ROW' + PASSING data + COLUMNS id int PATH '@id', + ordinality FOR ORDINALITY, + "COUNTRY_NAME" text, + country_id text PATH 'COUNTRY_ID', + size_sq_km float PATH 'SIZE[@unit = "sq_km"]', + size_other text PATH + 'concat(SIZE[@unit!="sq_km"], " ", SIZE[@unit!="sq_km"]/@unit)', + premier_name text PATH 'PREMIER_NAME' DEFAULT 'not specified') ; + + id | ordinality | COUNTRY_NAME | country_id | size_sq_km | size_other | premier_name +----+------------+--------------+------------+------------+--------------+--------------- + 1 | 1 | Australia | AU | | | not specified + 5 | 2 | Japan | JP | | 145935 sq_mi | Shinzo Abe + 6 | 3 | Singapore | SG | 697 | | not specified +]]></screen> + + The following example shows concatenation of multiple text() nodes, + usage of the column name as XPath filter, and the treatment of whitespace, + XML comments and processing instructions: + + <screen><![CDATA[ +CREATE TABLE xmlelements AS SELECT +xml $$ + <root> + <element> Hello<!-- xyxxz -->2a2<?aaaaa?> <!--x--> bbb<x>xxx</x>CC </element> + </root> +$$ AS data; + +SELECT xmltable.* + FROM xmlelements, XMLTABLE('/root' PASSING data COLUMNS element text); + element +---------------------- + Hello2a2 bbbCC +]]></screen> + </para> + + <para> + The following example illustrates how + the <literal>XMLNAMESPACES</literal> clause can be used to specify + the default namespace, and a list of additional namespaces + used in the XML document as well as in the XPath expressions: + + <screen><![CDATA[ +WITH xmldata(data) AS (VALUES (' +<example xmlns="http://example.com/myns" xmlns:B="http://example.com/b"> + <item foo="1" B:bar="2"/> + <item foo="3" B:bar="4"/> + <item foo="4" B:bar="5"/> +</example>'::xml) +) +SELECT xmltable.* + FROM XMLTABLE(XMLNAMESPACES('http://example.com/myns' AS x, + 'http://example.com/b' AS "B"), + '/x:example/x:item' + PASSING (SELECT data FROM xmldata) + COLUMNS foo int PATH '@foo', + bar int PATH '@B:bar'); + foo | bar +-----+----- + 1 | 2 + 3 | 4 + 4 | 5 +(3 rows) +]]></screen> + </para> + </sect3> </sect2> <sect2 id="functions-xml-mapping"> @@ -10770,6 +11164,14 @@ table2-mapping </row> <row> <entry><literal>-</literal></entry> + <entry><type>text[]</type></entry> + <entry>Delete multiple key/value pairs or <emphasis>string</emphasis> + elements from left operand. Key/value pairs are matched based + on their key value.</entry> + <entry><literal>'{"a": "b", "c": "d"}'::jsonb - '{a,c}'::text[] </literal></entry> + </row> + <row> + <entry><literal>-</literal></entry> <entry><type>integer</type></entry> <entry>Delete the array element with specified index (Negative integers count from the end). Throws an error if top level @@ -11174,12 +11576,12 @@ table2-mapping whose columns match the record type defined by <replaceable>base</> (see note below). </entry> - <entry><literal>select * from json_populate_record(null::myrowtype, '{"a":1,"b":2}')</literal></entry> + <entry><literal>select * from json_populate_record(null::myrowtype, '{"a": 1, "b": ["2", "a b"], "c": {"d": 4, "e": "a b c"}}')</literal></entry> <entry> <programlisting> - a | b ----+--- - 1 | 2 + a | b | c +---+-----------+------------- + 1 | {2,"a b"} | (4,"a b c") </programlisting> </entry> </row> @@ -11268,12 +11670,12 @@ table2-mapping explicitly define the structure of the record with an <literal>AS</> clause. </entry> - <entry><literal>select * from json_to_record('{"a":1,"b":[1,2,3],"c":"bar"}') as x(a int, b text, d text) </literal></entry> + <entry><literal>select * from json_to_record('{"a":1,"b":[1,2,3],"c":[1,2,3],"e":"bar","r": {"a": 123, "b": "a b c"}}') as x(a int, b text, c int[], d text, r myrowtype) </literal></entry> <entry> <programlisting> - a | b | d ----+---------+--- - 1 | [1,2,3] | + a | b | c | d | r +---+---------+---------+---+--------------- + 1 | [1,2,3] | {1,2,3} | | (123,"a b c") </programlisting> </entry> </row> @@ -11640,6 +12042,10 @@ nextval('foo'::text) <lineannotation><literal>foo</literal> is looked up at </para> </important> + <para> + This function requires <literal>USAGE</literal> + or <literal>UPDATE</literal> privilege on the sequence. + </para> </listitem> </varlistentry> @@ -11655,6 +12061,11 @@ nextval('foo'::text) <lineannotation><literal>foo</literal> is looked up at other sessions have executed <function>nextval</function> since the current session did. </para> + + <para> + This function requires <literal>USAGE</literal> + or <literal>SELECT</literal> privilege on the sequence. + </para> </listitem> </varlistentry> @@ -11671,6 +12082,11 @@ nextval('foo'::text) <lineannotation><literal>foo</literal> is looked up at <function>lastval</function> if <function>nextval</function> has not yet been called in the current session. </para> + + <para> + This function requires <literal>USAGE</literal> + or <literal>SELECT</literal> privilege on the last used sequence. + </para> </listitem> </varlistentry> @@ -11709,6 +12125,11 @@ SELECT setval('foo', 42, false); <lineannotation>Next <function>nextval</> wi back. </para> </important> + + <para> + This function requires <literal>UPDATE</literal> privilege on the + sequence. + </para> </listitem> </varlistentry> </variablelist> @@ -12775,13 +13196,14 @@ NULL baz</literallayout>(3 rows)</entry> <para> <firstterm>Aggregate functions</firstterm> compute a single result - from a set of input values. The built-in normal aggregate functions - are listed in - <xref linkend="functions-aggregate-table"> and - <xref linkend="functions-aggregate-statistics-table">. - The built-in ordered-set aggregate functions - are listed in <xref linkend="functions-orderedset-table"> and - <xref linkend="functions-hypothetical-table">. Grouping operations, + from a set of input values. The built-in general-purpose aggregate + functions are listed in <xref linkend="functions-aggregate-table"> + and statistical aggregates in <xref + linkend="functions-aggregate-statistics-table">. + The built-in within-group ordered-set aggregate functions + are listed in <xref linkend="functions-orderedset-table"> + while the built-in within-group hypothetical-set ones are in <xref + linkend="functions-hypothetical-table">. Grouping operations, which are closely related to aggregate functions, are listed in <xref linkend="functions-grouping-table">. The special syntax considerations for aggregate @@ -13699,9 +14121,6 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; <primary>percentile</primary> <secondary>continuous</secondary> </indexterm> - <indexterm> - <primary>median</primary> - </indexterm> <function>percentile_cont(<replaceable class="parameter">fraction</replaceable>) WITHIN GROUP (ORDER BY <replaceable class="parameter">sort_expression</replaceable>)</function> </entry> <entry> @@ -13737,7 +14156,7 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; <entry>No</entry> <entry> multiple continuous percentile: returns an array of results matching - the shape of the <literal>fractions</literal> parameter, with each + the shape of the <replaceable>fractions</replaceable> parameter, with each non-null element replaced by the value corresponding to that percentile </entry> </row> @@ -13782,7 +14201,7 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; <entry>No</entry> <entry> multiple discrete percentile: returns an array of results matching the - shape of the <literal>fractions</literal> parameter, with each non-null + shape of the <replaceable>fractions</replaceable> parameter, with each non-null element replaced by the input value corresponding to that percentile </entry> </row> @@ -14025,17 +14444,19 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; <para> The built-in window functions are listed in <xref linkend="functions-window-table">. Note that these functions - <emphasis>must</> be invoked using window function syntax; that is an + <emphasis>must</> be invoked using window function syntax, i.e., an <literal>OVER</> clause is required. </para> <para> - In addition to these functions, any built-in or user-defined normal - aggregate function (but not ordered-set or hypothetical-set aggregates) + In addition to these functions, any built-in or user-defined + general-purpose or statistical + aggregate (i.e., not ordered-set or hypothetical-set aggregates) can be used as a window function; see <xref linkend="functions-aggregate"> for a list of the built-in aggregates. Aggregate functions act as window functions only when an <literal>OVER</> - clause follows the call; otherwise they act as regular aggregates. + clause follows the call; otherwise they act as non-window aggregates + and return a single row for the entire set. </para> <table id="functions-window-table"> @@ -14100,7 +14521,7 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; <entry> <type>double precision</type> </entry> - <entry>relative rank of the current row: (<function>rank</> - 1) / (total rows - 1)</entry> + <entry>relative rank of the current row: (<function>rank</> - 1) / (total partition rows - 1)</entry> </row> <row> @@ -14113,7 +14534,7 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; <entry> <type>double precision</type> </entry> - <entry>relative rank of the current row: (number of rows preceding or peer with current row) / (total rows)</entry> + <entry>cumulative distribution: (number of partition rows preceding or peer with current row) / total partition rows</entry> </row> <row> @@ -14246,9 +14667,10 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; All of the functions listed in <xref linkend="functions-window-table"> depend on the sort ordering specified by the <literal>ORDER BY</> clause of the associated window - definition. Rows that are not distinct in the <literal>ORDER BY</> - ordering are said to be <firstterm>peers</>; the four ranking functions - are defined so that they give the same answer for any two peer rows. + definition. Rows that are not distinct when considering only the + <literal>ORDER BY</> columns are said to be <firstterm>peers</>. + The four ranking functions (including <function>cume_dist</>) are + defined so that they give the same answer for all peer rows. </para> <para> @@ -14291,6 +14713,14 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; </para> </note> + <para> + <function>cume_dist</> computes the fraction of partition rows that + are less than or equal to the current row and its peers, while + <function>percent_rank</> computes the fraction of partition rows that + are less than the current row, assuming the current row does not exist + in the partition. + </para> + </sect1> <sect1 id="functions-subquery"> @@ -15249,11 +15679,11 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n); postmaster.pid | 9 pg_ident.conf | 10 global | 11 - pg_clog | 12 + pg_xact | 12 pg_snapshots | 13 pg_multixact | 14 PG_VERSION | 15 - pg_xlog | 16 + pg_wal | 16 pg_hba.conf | 17 pg_stat_tmp | 18 pg_subtrans | 19 @@ -15306,6 +15736,12 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n); </row> <row> + <entry><literal><function>current_role</function></literal></entry> + <entry><type>name</type></entry> + <entry>equivalent to <function>current_user</function></entry> + </row> + + <row> <entry><literal><function>current_schema</function>[()]</literal></entry> <entry><type>name</type></entry> <entry>name of current schema</entry> @@ -15359,7 +15795,7 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n); <row> <entry><literal><function>pg_blocking_pids(<type>int</type>)</function></literal></entry> <entry><type>int[]</type></entry> - <entry>Process ID(s) that are blocking specified server process ID</entry> + <entry>Process ID(s) that are blocking specified server process ID from acquiring a lock</entry> </row> <row> @@ -15369,6 +15805,13 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n); </row> <row> + <entry><literal><function>pg_current_logfile(<optional><type>text</></optional>)</function></literal></entry> + <entry><type>text</type></entry> + <entry>Primary log file name, or log in the requested format, + currently in use by the logging collector</entry> + </row> + + <row> <entry><literal><function>pg_my_temp_schema()</function></literal></entry> <entry><type>oid</type></entry> <entry>OID of session's temporary schema, or 0 if none</entry> @@ -15399,6 +15842,12 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n); </row> <row> + <entry><literal><function>pg_safe_snapshot_blocking_pids(<type>int</type>)</function></literal></entry> + <entry><type>int[]</type></entry> + <entry>Process ID(s) that are blocking specified server process ID from acquiring a safe snapshot</entry> + </row> + + <row> <entry><literal><function>pg_trigger_depth()</function></literal></entry> <entry><type>int</type></entry> <entry>current nesting level of <productname>PostgreSQL</> triggers @@ -15433,8 +15882,11 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n); <note> <para> - <function>current_catalog</function>, <function>current_schema</function>, - <function>current_user</function>, <function>session_user</function>, + <function>current_catalog</function>, + <function>current_role</function>, + <function>current_schema</function>, + <function>current_user</function>, + <function>session_user</function>, and <function>user</function> have special syntactic status in <acronym>SQL</acronym>: they must be called without trailing parentheses. (In PostgreSQL, parentheses can optionally be used with @@ -15455,6 +15907,10 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n); </indexterm> <indexterm> + <primary>current_role</primary> + </indexterm> + + <indexterm> <primary>current_schema</primary> </indexterm> @@ -15505,6 +15961,11 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n); functions with the attribute <literal>SECURITY DEFINER</literal>. In Unix parlance, the session user is the <quote>real user</quote> and the current user is the <quote>effective user</quote>. + <function>current_role</function> and <function>user</function> are + synonyms for <function>current_user</function>. (The SQL standard draws + a distinction between <function>current_role</function> + and <function>current_user</function>, but <productname>PostgreSQL</> + does not, since it unifies users and roles into a single kind of entity.) </para> <para> @@ -15592,6 +16053,45 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, .. </para> <indexterm> + <primary>pg_current_logfile</primary> + </indexterm> + + <indexterm> + <primary>Logging</primary> + <secondary>pg_current_logfile function</secondary> + </indexterm> + + <indexterm> + <primary>current_logfiles</primary> + <secondary>and the pg_current_logfile function</secondary> + </indexterm> + + <indexterm> + <primary>Logging</primary> + <secondary>current_logfiles file and the pg_current_logfile + function</secondary> + </indexterm> + + <para> + <function>pg_current_logfile</function> returns, as <type>text</type>, + the path of the log file(s) currently in use by the logging collector. + The path includes the <xref linkend="guc-log-directory"> directory + and the log file name. Log collection must be enabled or the return value + is <literal>NULL</literal>. When multiple log files exist, each in a + different format, <function>pg_current_logfile</function> called + without arguments returns the path of the file having the first format + found in the ordered list: <systemitem>stderr</>, <systemitem>csvlog</>. + <literal>NULL</literal> is returned when no log file has any of these + formats. To request a specific file format supply, as <type>text</type>, + either <systemitem>csvlog</> or <systemitem>stderr</> as the value of the + optional parameter. The return value is <literal>NULL</literal> when the + log format requested is not a configured + <xref linkend="guc-log-destination">. The + <function>pg_current_logfiles</function> reflects the contents of the + <filename>current_logfiles</> file. + </para> + + <indexterm> <primary>pg_my_temp_schema</primary> </indexterm> @@ -15639,6 +16139,25 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, .. </para> <indexterm> + <primary>pg_safe_snapshot_blocking_pids</primary> + </indexterm> + + <para> + <function>pg_safe_snapshot_blocking_pids</function> returns an array of + the process IDs of the sessions that are blocking the server process with + the specified process ID from acquiring a safe snapshot, or an empty array + if there is no such server process or it is not blocked. A session + running a <literal>SERIALIZABLE</literal> transaction blocks + a <literal>SERIALIZABLE READ ONLY DEFERRABLE</literal> transaction from + acquiring a snapshot until the latter determines that it is safe to avoid + taking any predicate locks. See <xref linkend="xact-serializable"> for + more information about serializable and deferrable transactions. Frequent + calls to this function could have some impact on database performance, + because it needs access to the predicate lock manager's shared + state for a short time. + </para> + + <indexterm> <primary>version</primary> </indexterm> @@ -15840,6 +16359,21 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, .. <entry>does current user have privilege for tablespace</entry> </row> <row> + <entry><literal><function>has_type_privilege</function>(<parameter>user</parameter>, + <parameter>type</parameter>, + <parameter>privilege</parameter>)</literal> + </entry> + <entry><type>boolean</type></entry> + <entry>does user have privilege for type</entry> + </row> + <row> + <entry><literal><function>has_type_privilege</function>(<parameter>type</parameter>, + <parameter>privilege</parameter>)</literal> + </entry> + <entry><type>boolean</type></entry> + <entry>does current user have privilege for type</entry> + </row> + <row> <entry><literal><function>pg_has_role</function>(<parameter>user</parameter>, <parameter>role</parameter>, <parameter>privilege</parameter>)</literal> @@ -15898,6 +16432,9 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, .. <primary>has_tablespace_privilege</primary> </indexterm> <indexterm> + <primary>has_type_privilege</primary> + </indexterm> + <indexterm> <primary>pg_has_role</primary> </indexterm> <indexterm> @@ -16052,6 +16589,18 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); </para> <para> + <function>has_type_privilege</function> checks whether a user + can access a type in a particular way. + Its argument possibilities + are analogous to <function>has_table_privilege</function>. + When specifying a type by a text string rather than by OID, + the allowed input is the same as for the <type>regtype</> data type + (see <xref linkend="datatype-oid">). + The desired access privilege type must evaluate to + <literal>USAGE</literal>. + </para> + + <para> <function>pg_has_role</function> checks whether a user can access a role in a particular way. Its argument possibilities @@ -16137,6 +16686,12 @@ SELECT relname FROM pg_class WHERE pg_table_is_visible(oid); <entry>is operator family visible in search path</entry> </row> <row> + <entry><literal><function>pg_statistics_obj_is_visible(<parameter>stat_oid</parameter>)</function></literal> + </entry> + <entry><type>boolean</type></entry> + <entry>is statistics object visible in search path</entry> + </row> + <row> <entry><literal><function>pg_table_is_visible(<parameter>table_oid</parameter>)</function></literal> </entry> <entry><type>boolean</type></entry> @@ -16195,6 +16750,9 @@ SELECT relname FROM pg_class WHERE pg_table_is_visible(oid); <primary>pg_opfamily_is_visible</primary> </indexterm> <indexterm> + <primary>pg_statistics_obj_is_visible</primary> + </indexterm> + <indexterm> <primary>pg_table_is_visible</primary> </indexterm> <indexterm> @@ -16290,6 +16848,10 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); </indexterm> <indexterm> + <primary>pg_get_statisticsobjdef</primary> + </indexterm> + + <indexterm> <primary>pg_get_triggerdef</primary> </indexterm> @@ -16459,6 +17021,11 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); uses</entry> </row> <row> + <entry><literal><function>pg_get_statisticsobjdef(<parameter>statobj_oid</parameter>)</function></literal></entry> + <entry><type>text</type></entry> + <entry>get <command>CREATE STATISTICS</> command for extended statistics object</entry> + </row> + <row> <entry><function>pg_get_triggerdef</function>(<parameter>trigger_oid</parameter>)</entry> <entry><type>text</type></entry> <entry>get <command>CREATE [ CONSTRAINT ] TRIGGER</> command for trigger</entry> @@ -16603,19 +17170,20 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); <para> <function>pg_get_constraintdef</function>, <function>pg_get_indexdef</function>, <function>pg_get_ruledef</function>, - and <function>pg_get_triggerdef</function>, respectively reconstruct the - creating command for a constraint, index, rule, or trigger. (Note that this - is a decompiled reconstruction, not the original text of the command.) - <function>pg_get_expr</function> decompiles the internal form of an - individual expression, such as the default value for a column. It can be - useful when examining the contents of system catalogs. If the expression - might contain Vars, specify the OID of the relation they refer to as the - second parameter; if no Vars are expected, zero is sufficient. - <function>pg_get_viewdef</function> reconstructs the <command>SELECT</> - query that defines a view. Most of these functions come in two variants, - one of which can optionally <quote>pretty-print</> the result. The - pretty-printed format is more readable, but the default format is more - likely to be interpreted the same way by future versions of + <function>pg_get_statisticsobjdef</function>, and + <function>pg_get_triggerdef</function>, respectively reconstruct the + creating command for a constraint, index, rule, extended statistics object, + or trigger. (Note that this is a decompiled reconstruction, not the + original text of the command.) <function>pg_get_expr</function> decompiles + the internal form of an individual expression, such as the default value + for a column. It can be useful when examining the contents of system + catalogs. If the expression might contain Vars, specify the OID of the + relation they refer to as the second parameter; if no Vars are expected, + zero is sufficient. <function>pg_get_viewdef</function> reconstructs the + <command>SELECT</> query that defines a view. Most of these functions come + in two variants, one of which can optionally <quote>pretty-print</> the + result. The pretty-printed format is more readable, but the default format + is more likely to be interpreted the same way by future versions of <productname>PostgreSQL</>; avoid using pretty-printed output for dump purposes. Passing <literal>false</> for the pretty-print parameter yields the same result as the variant that does not have the parameter at all. @@ -16799,7 +17367,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); <para> <function>pg_options_to_table</function> returns the set of storage option name/value pairs - (<literal>option_name</>/<literal>option_value</>) when passed + (<replaceable>option_name</>/<replaceable>option_value</>) when passed <structname>pg_class</>.<structfield>reloptions</> or <structname>pg_attribute</>.<structfield>attoptions</>. </para> @@ -17082,6 +17650,10 @@ SELECT collation for ('foo' COLLATE "de_DE"); </indexterm> <indexterm> + <primary>txid_current_if_assigned</primary> + </indexterm> + + <indexterm> <primary>txid_current_snapshot</primary> </indexterm> @@ -17101,6 +17673,10 @@ SELECT collation for ('foo' COLLATE "de_DE"); <primary>txid_visible_in_snapshot</primary> </indexterm> + <indexterm> + <primary>txid_status</primary> + </indexterm> + <para> The functions shown in <xref linkend="functions-txid-snapshot"> provide server transaction information in an exportable form. The main @@ -17127,6 +17703,11 @@ SELECT collation for ('foo' COLLATE "de_DE"); <entry>get current transaction ID, assigning a new one if the current transaction does not have one</entry> </row> <row> + <entry><literal><function>txid_current_if_assigned()</function></literal></entry> + <entry><type>bigint</type></entry> + <entry>same as <function>txid_current()</function> but returns null instead of assigning an xid if none is already assigned</entry> + </row> + <row> <entry><literal><function>txid_current_snapshot()</function></literal></entry> <entry><type>txid_snapshot</type></entry> <entry>get current snapshot</entry> @@ -17151,6 +17732,11 @@ SELECT collation for ('foo' COLLATE "de_DE"); <entry><type>boolean</type></entry> <entry>is transaction ID visible in snapshot? (do not use with subtransaction ids)</entry> </row> + <row> + <entry><literal><function>txid_status(<parameter>bigint</parameter>)</function></literal></entry> + <entry><type>txid_status</type></entry> + <entry>report the status of the given xact - <literal>committed</literal>, <literal>aborted</literal>, <literal>in progress</literal>, or NULL if the txid is too old</entry> + </row> </tbody> </tgroup> </table> @@ -17221,6 +17807,24 @@ SELECT collation for ('foo' COLLATE "de_DE"); </para> <para> + <function>txid_status(bigint)</> reports the commit status of a recent + transaction. Applications may use it to determine whether a transaction + committed or aborted when the application and database server become + disconnected while a <literal>COMMIT</literal> is in progress. + The status of a transaction will be reported as either + <literal>in progress</>, + <literal>committed</>, or <literal>aborted</>, provided that the + transaction is recent enough that the system retains the commit status + of that transaction. If is old enough that no references to that + transaction survive in the system and the commit status information has + been discarded, this function will return NULL. Note that prepared + transactions are reported as <literal>in progress</>; applications must + check <link + linkend="view-pg-prepared-xacts"><literal>pg_prepared_xacts</></> if they + need to determine whether the txid is a prepared transaction. + </para> + + <para> The functions shown in <xref linkend="functions-commit-timestamp"> provide information about transactions that have been already committed. These functions mainly provide information about when the transactions @@ -17343,17 +17947,17 @@ SELECT collation for ('foo' COLLATE "de_DE"); <tbody> <row> - <entry><literal>checkpoint_location</literal></entry> + <entry><literal>checkpoint_lsn</literal></entry> <entry><type>pg_lsn</type></entry> </row> <row> - <entry><literal>prior_location</literal></entry> + <entry><literal>prior_lsn</literal></entry> <entry><type>pg_lsn</type></entry> </row> <row> - <entry><literal>redo_location</literal></entry> + <entry><literal>redo_lsn</literal></entry> <entry><type>pg_lsn</type></entry> </row> @@ -17545,11 +18149,6 @@ SELECT collation for ('foo' COLLATE "de_DE"); </row> <row> - <entry><literal>bigint_timestamps</literal></entry> - <entry><type>boolean</type></entry> - </row> - - <row> <entry><literal>float4_pass_by_value</literal></entry> <entry><type>boolean</type></entry> </row> @@ -17586,7 +18185,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); <tbody> <row> - <entry><literal>min_recovery_end_location</literal></entry> + <entry><literal>min_recovery_end_lsn</literal></entry> <entry><type>pg_lsn</type></entry> </row> @@ -17596,12 +18195,12 @@ SELECT collation for ('foo' COLLATE "de_DE"); </row> <row> - <entry><literal>backup_start_location</literal></entry> + <entry><literal>backup_start_lsn</literal></entry> <entry><type>pg_lsn</type></entry> </row> <row> - <entry><literal>backup_end_location</literal></entry> + <entry><literal>backup_end_lsn</literal></entry> <entry><type>pg_lsn</type></entry> </row> @@ -17753,7 +18352,7 @@ SELECT set_config('log_statement_stats', 'off', false); The functions shown in <xref linkend="functions-admin-signal-table"> send control signals to other server processes. Use of these functions is restricted to - superusers by default but access may be granted to others with the + superusers by default but access may be granted to others using <command>GRANT</command>, with noted exceptions. </para> @@ -17856,13 +18455,13 @@ SELECT set_config('log_statement_stats', 'off', false); <primary>pg_create_restore_point</primary> </indexterm> <indexterm> - <primary>pg_current_xlog_flush_location</primary> + <primary>pg_current_wal_flush_lsn</primary> </indexterm> <indexterm> - <primary>pg_current_xlog_insert_location</primary> + <primary>pg_current_wal_insert_lsn</primary> </indexterm> <indexterm> - <primary>pg_current_xlog_location</primary> + <primary>pg_current_wal_lsn</primary> </indexterm> <indexterm> <primary>pg_start_backup</primary> @@ -17877,16 +18476,16 @@ SELECT set_config('log_statement_stats', 'off', false); <primary>pg_backup_start_time</primary> </indexterm> <indexterm> - <primary>pg_switch_xlog</primary> + <primary>pg_switch_wal</primary> </indexterm> <indexterm> - <primary>pg_xlogfile_name</primary> + <primary>pg_walfile_name</primary> </indexterm> <indexterm> - <primary>pg_xlogfile_name_offset</primary> + <primary>pg_walfile_name_offset</primary> </indexterm> <indexterm> - <primary>pg_xlog_location_diff</primary> + <primary>pg_wal_lsn_diff</primary> </indexterm> <para> @@ -17894,7 +18493,7 @@ SELECT set_config('log_statement_stats', 'off', false); linkend="functions-admin-backup-table"> assist in making on-line backups. These functions cannot be executed during recovery (except <function>pg_is_in_backup</function>, <function>pg_backup_start_time</function> - and <function>pg_xlog_location_diff</function>). + and <function>pg_wal_lsn_diff</function>). </para> <table id="functions-admin-backup-table"> @@ -17915,24 +18514,24 @@ SELECT set_config('log_statement_stats', 'off', false); </row> <row> <entry> - <literal><function>pg_current_xlog_flush_location()</function></literal> + <literal><function>pg_current_wal_flush_lsn()</function></literal> </entry> <entry><type>pg_lsn</type></entry> - <entry>Get current transaction log flush location</entry> + <entry>Get current write-ahead log flush location</entry> </row> <row> <entry> - <literal><function>pg_current_xlog_insert_location()</function></literal> + <literal><function>pg_current_wal_insert_lsn()</function></literal> </entry> <entry><type>pg_lsn</type></entry> - <entry>Get current transaction log insert location</entry> + <entry>Get current write-ahead log insert location</entry> </row> <row> <entry> - <literal><function>pg_current_xlog_location()</function></literal> + <literal><function>pg_current_wal_lsn()</function></literal> </entry> <entry><type>pg_lsn</type></entry> - <entry>Get current transaction log write location</entry> + <entry>Get current write-ahead log write location</entry> </row> <row> <entry> @@ -17950,7 +18549,7 @@ SELECT set_config('log_statement_stats', 'off', false); </row> <row> <entry> - <literal><function>pg_stop_backup(<parameter>exclusive</> <type>boolean</>)</function></literal> + <literal><function>pg_stop_backup(<parameter>exclusive</> <type>boolean</> <optional>, <parameter>wait_for_archive</> <type>boolean</> </optional>)</function></literal> </entry> <entry><type>setof record</type></entry> <entry>Finish performing exclusive or non-exclusive on-line backup (restricted to superusers by default, but other users can be granted EXECUTE to run the function)</entry> @@ -17971,31 +18570,31 @@ SELECT set_config('log_statement_stats', 'off', false); </row> <row> <entry> - <literal><function>pg_switch_xlog()</function></literal> + <literal><function>pg_switch_wal()</function></literal> </entry> <entry><type>pg_lsn</type></entry> - <entry>Force switch to a new transaction log file (restricted to superusers by default, but other users can be granted EXECUTE to run the function)</entry> + <entry>Force switch to a new write-ahead log file (restricted to superusers by default, but other users can be granted EXECUTE to run the function)</entry> </row> <row> <entry> - <literal><function>pg_xlogfile_name(<parameter>location</> <type>pg_lsn</>)</function></literal> + <literal><function>pg_walfile_name(<parameter>lsn</> <type>pg_lsn</>)</function></literal> </entry> <entry><type>text</type></entry> - <entry>Convert transaction log location string to file name</entry> + <entry>Convert write-ahead log location to file name</entry> </row> <row> <entry> - <literal><function>pg_xlogfile_name_offset(<parameter>location</> <type>pg_lsn</>)</function></literal> + <literal><function>pg_walfile_name_offset(<parameter>lsn</> <type>pg_lsn</>)</function></literal> </entry> <entry><type>text</>, <type>integer</></entry> - <entry>Convert transaction log location string to file name and decimal byte offset within file</entry> + <entry>Convert write-ahead log location to file name and decimal byte offset within file</entry> </row> <row> <entry> - <literal><function>pg_xlog_location_diff(<parameter>location</> <type>pg_lsn</>, <parameter>location</> <type>pg_lsn</>)</function></literal> + <literal><function>pg_wal_lsn_diff(<parameter>lsn</> <type>pg_lsn</>, <parameter>lsn</> <type>pg_lsn</>)</function></literal> </entry> <entry><type>numeric</></entry> - <entry>Calculate the difference between two transaction log locations</entry> + <entry>Calculate the difference between two write-ahead log locations</entry> </row> </tbody> </tgroup> @@ -18008,7 +18607,7 @@ SELECT set_config('log_statement_stats', 'off', false); backup label file (<filename>backup_label</>) and, if there are any links in the <filename>pg_tblspc/</> directory, a tablespace map file (<filename>tablespace_map</>) into the database cluster's data directory, - performs a checkpoint, and then returns the backup's starting transaction + performs a checkpoint, and then returns the backup's starting write-ahead log location as text. The user can ignore this result value, but it is provided in case it is useful. When used in non-exclusive mode, the contents of these files are instead returned by the @@ -18034,34 +18633,40 @@ postgres=# select pg_start_backup('label_goes_here'); <function>pg_start_backup</>. In a non-exclusive backup, the contents of the <filename>backup_label</> and <filename>tablespace_map</> are returned in the result of the function, and should be written to files in the - backup (and not in the data directory). + backup (and not in the data directory). There is an optional second + parameter of type boolean. If false, the <function>pg_stop_backup</> + will return immediately after the backup is completed without waiting for + WAL to be archived. This behavior is only useful for backup + software which independently monitors WAL archiving. Otherwise, WAL + required to make the backup consistent might be missing and make the backup + useless. </para> <para> - The function also creates a backup history file in the transaction log + The function also creates a backup history file in the write-ahead log archive area. The history file includes the label given to - <function>pg_start_backup</>, the starting and ending transaction log locations for + <function>pg_start_backup</>, the starting and ending write-ahead log locations for the backup, and the starting and ending times of the backup. The return - value is the backup's ending transaction log location (which again + value is the backup's ending write-ahead log location (which again can be ignored). After recording the ending location, the current - transaction log insertion - point is automatically advanced to the next transaction log file, so that the - ending transaction log file can be archived immediately to complete the backup. + write-ahead log insertion + point is automatically advanced to the next write-ahead log file, so that the + ending write-ahead log file can be archived immediately to complete the backup. </para> <para> - <function>pg_switch_xlog</> moves to the next transaction log file, allowing the + <function>pg_switch_wal</> moves to the next write-ahead log file, allowing the current file to be archived (assuming you are using continuous archiving). - The return value is the ending transaction log location + 1 within the just-completed transaction log file. - If there has been no transaction log activity since the last transaction log switch, - <function>pg_switch_xlog</> does nothing and returns the start location - of the transaction log file currently in use. + The return value is the ending write-ahead log location + 1 within the just-completed write-ahead log file. + If there has been no write-ahead log activity since the last write-ahead log switch, + <function>pg_switch_wal</> does nothing and returns the start location + of the write-ahead log file currently in use. </para> <para> - <function>pg_create_restore_point</> creates a named transaction log + <function>pg_create_restore_point</> creates a named write-ahead log record that can be used as recovery target, and returns the corresponding - transaction log location. The given name can then be used with + write-ahead log location. The given name can then be used with <xref linkend="recovery-target-name"> to specify the point up to which recovery will proceed. Avoid creating multiple restore points with the same name, since recovery will stop at the first one whose name matches @@ -18069,36 +18674,36 @@ postgres=# select pg_start_backup('label_goes_here'); </para> <para> - <function>pg_current_xlog_location</> displays the current transaction log write + <function>pg_current_wal_lsn</> displays the current write-ahead log write location in the same format used by the above functions. Similarly, - <function>pg_current_xlog_insert_location</> displays the current transaction log - insertion point and <function>pg_current_xlog_flush_location</> displays the - current transaction log flush point. The insertion point is the <quote>logical</> - end of the transaction log at any instant, while the write location is the end of + <function>pg_current_wal_insert_lsn</> displays the current write-ahead log + insertion location and <function>pg_current_wal_flush_lsn</> displays the + current write-ahead log flush location. The insertion location is the <quote>logical</> + end of the write-ahead log at any instant, while the write location is the end of what has actually been written out from the server's internal buffers and flush location is the location guaranteed to be written to durable storage. The write location is the end of what can be examined from outside the server, and is usually - what you want if you are interested in archiving partially-complete transaction log - files. The insertion and flush points are made available primarily for server + what you want if you are interested in archiving partially-complete write-ahead log + files. The insertion and flush locations are made available primarily for server debugging purposes. These are both read-only operations and do not require superuser permissions. </para> <para> - You can use <function>pg_xlogfile_name_offset</> to extract the - corresponding transaction log file name and byte offset from the results of any of the + You can use <function>pg_walfile_name_offset</> to extract the + corresponding write-ahead log file name and byte offset from the results of any of the above functions. For example: <programlisting> -postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); +postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); file_name | file_offset --------------------------+------------- 00000001000000000000000D | 4039624 (1 row) </programlisting> - Similarly, <function>pg_xlogfile_name</> extracts just the transaction log file name. - When the given transaction log location is exactly at a transaction log file boundary, both - these functions return the name of the preceding transaction log file. - This is usually the desired behavior for managing transaction log archiving + Similarly, <function>pg_walfile_name</> extracts just the write-ahead log file name. + When the given write-ahead log location is exactly at a write-ahead log file boundary, both + these functions return the name of the preceding write-ahead log file. + This is usually the desired behavior for managing write-ahead log archiving behavior, since the preceding file is the last one that currently needs to be archived. </para> @@ -18110,8 +18715,8 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); </para> <para> - <function>pg_xlog_location_diff</> calculates the difference in bytes - between two transaction log locations. It can be used with + <function>pg_wal_lsn_diff</> calculates the difference in bytes + between two write-ahead log locations. It can be used with <structname>pg_stat_replication</structname> or some functions shown in <xref linkend="functions-admin-backup-table"> to get the replication lag. </para> @@ -18130,10 +18735,10 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <primary>pg_is_in_recovery</primary> </indexterm> <indexterm> - <primary>pg_last_xlog_receive_location</primary> + <primary>pg_last_wal_receive_lsn</primary> </indexterm> <indexterm> - <primary>pg_last_xlog_replay_location</primary> + <primary>pg_last_wal_replay_lsn</primary> </indexterm> <indexterm> <primary>pg_last_xact_replay_timestamp</primary> @@ -18165,10 +18770,10 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); </row> <row> <entry> - <literal><function>pg_last_xlog_receive_location()</function></literal> + <literal><function>pg_last_wal_receive_lsn()</function></literal> </entry> <entry><type>pg_lsn</type></entry> - <entry>Get last transaction log location received and synced to disk by + <entry>Get last write-ahead log location received and synced to disk by streaming replication. While streaming replication is in progress this will increase monotonically. If recovery has completed this will remain static at @@ -18179,10 +18784,10 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); </row> <row> <entry> - <literal><function>pg_last_xlog_replay_location()</function></literal> + <literal><function>pg_last_wal_replay_lsn()</function></literal> </entry> <entry><type>pg_lsn</type></entry> - <entry>Get last transaction log location replayed during recovery. + <entry>Get last write-ahead log location replayed during recovery. If recovery is still in progress this will increase monotonically. If recovery has completed then this value will remain static at the value of the last WAL record applied during that recovery. @@ -18211,13 +18816,13 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); </table> <indexterm> - <primary>pg_is_xlog_replay_paused</primary> + <primary>pg_is_wal_replay_paused</primary> </indexterm> <indexterm> - <primary>pg_xlog_replay_pause</primary> + <primary>pg_wal_replay_pause</primary> </indexterm> <indexterm> - <primary>pg_xlog_replay_resume</primary> + <primary>pg_wal_replay_resume</primary> </indexterm> <para> @@ -18237,7 +18842,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <tbody> <row> <entry> - <literal><function>pg_is_xlog_replay_paused()</function></literal> + <literal><function>pg_is_wal_replay_paused()</function></literal> </entry> <entry><type>bool</type></entry> <entry>True if recovery is paused. @@ -18245,7 +18850,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); </row> <row> <entry> - <literal><function>pg_xlog_replay_pause()</function></literal> + <literal><function>pg_wal_replay_pause()</function></literal> </entry> <entry><type>void</type></entry> <entry>Pauses recovery immediately (restricted to superusers by default, but other users can be granted EXECUTE to run the function). @@ -18253,7 +18858,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); </row> <row> <entry> - <literal><function>pg_xlog_replay_resume()</function></literal> + <literal><function>pg_wal_replay_resume()</function></literal> </entry> <entry><type>void</type></entry> <entry>Restarts recovery if it was paused (restricted to superusers by default, but other users can be granted EXECUTE to run the function). @@ -18405,10 +19010,10 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <indexterm> <primary>pg_create_physical_replication_slot</primary> </indexterm> - <literal><function>pg_create_physical_replication_slot(<parameter>slot_name</parameter> <type>name</type> <optional>, <parameter>immediately_reserve</> <type>boolean</> </optional>)</function></literal> + <literal><function>pg_create_physical_replication_slot(<parameter>slot_name</parameter> <type>name</type> <optional>, <parameter>immediately_reserve</> <type>boolean</>, <parameter>temporary</> <type>boolean</></optional>)</function></literal> </entry> <entry> - (<parameter>slot_name</parameter> <type>name</type>, <parameter>xlog_position</parameter> <type>pg_lsn</type>) + (<parameter>slot_name</parameter> <type>name</type>, <parameter>lsn</parameter> <type>pg_lsn</type>) </entry> <entry> Creates a new physical replication slot named @@ -18418,7 +19023,11 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); the <acronym>LSN</> is reserved on first connection from a streaming replication client. Streaming changes from a physical slot is only possible with the streaming-replication protocol — - see <xref linkend="protocol-replication">. This function corresponds + see <xref linkend="protocol-replication">. The optional third + parameter, <parameter>temporary</>, when set to true, specifies that + the slot should not be permanently stored to disk and is only meant + for use by current session. Temporary slots are also + released upon any error. This function corresponds to the replication protocol command <literal>CREATE_REPLICATION_SLOT ... PHYSICAL</literal>. </entry> @@ -18436,7 +19045,8 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <entry> Drops the physical or logical replication slot named <parameter>slot_name</parameter>. Same as replication protocol - command <literal>DROP_REPLICATION_SLOT</>. + command <literal>DROP_REPLICATION_SLOT</>. For logical slots, this must + be called when connected to the same database the slot was created on. </entry> </row> @@ -18445,15 +19055,19 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <indexterm> <primary>pg_create_logical_replication_slot</primary> </indexterm> - <literal><function>pg_create_logical_replication_slot(<parameter>slot_name</parameter> <type>name</type>, <parameter>plugin</parameter> <type>name</type>)</function></literal> + <literal><function>pg_create_logical_replication_slot(<parameter>slot_name</parameter> <type>name</type>, <parameter>plugin</parameter> <type>name</type> <optional>, <parameter>temporary</> <type>boolean</></optional>)</function></literal> </entry> <entry> - (<parameter>slot_name</parameter> <type>name</type>, <parameter>xlog_position</parameter> <type>pg_lsn</type>) + (<parameter>slot_name</parameter> <type>name</type>, <parameter>lsn</parameter> <type>pg_lsn</type>) </entry> <entry> Creates a new logical (decoding) replication slot named <parameter>slot_name</parameter> using the output plugin - <parameter>plugin</parameter>. A call to this function has the same + <parameter>plugin</parameter>. The optional third + parameter, <parameter>temporary</>, when set to true, specifies that + the slot should not be permanently stored to disk and is only meant + for use by current session. Temporary slots are also + released upon any error. A call to this function has the same effect as the replication protocol command <literal>CREATE_REPLICATION_SLOT ... LOGICAL</literal>. </entry> @@ -18467,7 +19081,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <literal><function>pg_logical_slot_get_changes(<parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>int</type>, VARIADIC <parameter>options</parameter> <type>text[]</type>)</function></literal> </entry> <entry> - (<parameter>location</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>text</type>) + (<parameter>lsn</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>text</type>) </entry> <entry> Returns changes in the slot <parameter>slot_name</parameter>, starting @@ -18492,7 +19106,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <literal><function>pg_logical_slot_peek_changes(<parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>int</type>, VARIADIC <parameter>options</parameter> <type>text[]</type>)</function></literal> </entry> <entry> - (<parameter>location</parameter> <type>text</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>text</type>) + (<parameter>lsn</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>text</type>) </entry> <entry> Behaves just like @@ -18510,7 +19124,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <literal><function>pg_logical_slot_get_binary_changes(<parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>int</type>, VARIADIC <parameter>options</parameter> <type>text[]</type>)</function></literal> </entry> <entry> - (<parameter>location</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>bytea</type>) + (<parameter>lsn</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>bytea</type>) </entry> <entry> Behaves just like @@ -18527,7 +19141,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <literal><function>pg_logical_slot_peek_binary_changes(<parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>int</type>, VARIADIC <parameter>options</parameter> <type>text[]</type>)</function></literal> </entry> <entry> - (<parameter>location</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>bytea</type>) + (<parameter>lsn</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>bytea</type>) </entry> <entry> Behaves just like @@ -18562,7 +19176,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <literal><function>pg_replication_origin_drop(<parameter>node_name</parameter> <type>text</type>)</function></literal> </entry> <entry> - void + <type>void</> </entry> <entry> Delete a previously created replication origin, including any @@ -18594,7 +19208,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <literal><function>pg_replication_origin_session_setup(<parameter>node_name</parameter> <type>text</type>)</function></literal> </entry> <entry> - void + <type>void</> </entry> <entry> Mark the current session as replaying from the given @@ -18612,7 +19226,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <literal><function>pg_replication_origin_session_reset()</function></literal> </entry> <entry> - void + <type>void</> </entry> <entry> Cancel the effects @@ -18646,7 +19260,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <type>pg_lsn</type> </entry> <entry> - Return the replay position for the replication origin configured in + Return the replay location for the replication origin configured in the current session. The parameter <parameter>flush</parameter> determines whether the corresponding local transaction will be guaranteed to have been flushed to disk or not. @@ -18661,7 +19275,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <literal><function>pg_replication_origin_xact_setup(<parameter>origin_lsn</parameter> <type>pg_lsn</type>, <parameter>origin_timestamp</parameter> <type>timestamptz</type>)</function></literal> </entry> <entry> - void + <type>void</> </entry> <entry> Mark the current transaction as replaying a transaction that has @@ -18680,7 +19294,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <literal><function>pg_replication_origin_xact_reset()</function></literal> </entry> <entry> - void + <type>void</> </entry> <entry> Cancel the effects of @@ -18689,19 +19303,19 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); </row> <row> - <entry> + <entry id="pg-replication-origin-advance"> <indexterm> <primary>pg_replication_origin_advance</primary> </indexterm> - <literal>pg_replication_origin_advance<function>(<parameter>node_name</parameter> <type>text</type>, <parameter>pos</parameter> <type>pg_lsn</type>)</function></literal> + <literal>pg_replication_origin_advance<function>(<parameter>node_name</parameter> <type>text</type>, <parameter>lsn</parameter> <type>pg_lsn</type>)</function></literal> </entry> <entry> - void + <type>void</> </entry> <entry> Set replication progress for the given node to the given - position. This primarily is useful for setting up the initial position - or a new position after configuration changes and similar. Be aware + location. This primarily is useful for setting up the initial location + or a new location after configuration changes and similar. Be aware that careless use of this function can lead to inconsistently replicated data. </entry> @@ -18718,7 +19332,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <type>pg_lsn</type> </entry> <entry> - Return the replay position for the given replication origin. The + Return the replay location for the given replication origin. The parameter <parameter>flush</parameter> determines whether the corresponding local transaction will be guaranteed to have been flushed to disk or not. @@ -18963,9 +19577,11 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); accept the OID or name of a database or tablespace, and return the total disk space used therein. To use <function>pg_database_size</function>, you must have <literal>CONNECT</> permission on the specified database - (which is granted by default). To use <function>pg_tablespace_size</>, - you must have <literal>CREATE</> permission on the specified tablespace, - unless it is the default tablespace for the current database. + (which is granted by default), or be a member of the <literal>pg_read_all_stats</> + role. To use <function>pg_tablespace_size</>, you must have + <literal>CREATE</> permission on the specified tablespace, or be a member + of the <literal>pg_read_all_stats</> role unless it is the default tablespace for + the current database. </para> <para> @@ -19144,6 +19760,63 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); in the database's default tablespace, the tablespace can be specified as 0. </para> + <para> + <xref linkend="functions-admin-collation"> lists functions used to manage + collations. + </para> + + <table id="functions-admin-collation"> + <title>Collation Management Functions</title> + <tgroup cols="3"> + <thead> + <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row> + </thead> + + <tbody> + <row> + <entry> + <indexterm><primary>pg_collation_actual_version</primary></indexterm> + <literal><function>pg_collation_actual_version(<type>oid</>)</function></literal> + </entry> + <entry><type>text</type></entry> + <entry>Return actual version of collation from operating system</entry> + </row> + <row> + <entry> + <indexterm><primary>pg_import_system_collations</primary></indexterm> + <literal><function>pg_import_system_collations(<parameter>if_not_exists</> <type>boolean</>, <parameter>schema</> <type>regnamespace</>)</function></literal> + </entry> + <entry><type>void</type></entry> + <entry>Import operating system collations</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + <function>pg_collation_actual_version</function> returns the actual + version of the collation object as it is currently installed in the + operating system. If this is different from the value + in <literal>pg_collation.collversion</literal>, then objects depending on + the collation might need to be rebuilt. See also + <xref linkend="sql-altercollation">. + </para> + + <para> + <function>pg_import_system_collations</> populates the system + catalog <literal>pg_collation</literal> with collations based on all the + locales it finds on the operating system. This is + what <command>initdb</command> uses; + see <xref linkend="collation-managing"> for more details. If additional + locales are installed into the operating system later on, this function + can be run again to add collations for the new locales. In that case, the + parameter <parameter>if_not_exists</parameter> should be set to true to + skip over existing collations. The <parameter>schema</parameter> + parameter would typically be <literal>pg_catalog</literal>, but that is + not a requirement. (Collation objects based on locales that are no longer + present on the operating system are never removed by this function.) + </para> + </sect2> <sect2 id="functions-admin-index"> @@ -19157,6 +19830,14 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <primary>gin_clean_pending_list</primary> </indexterm> + <indexterm> + <primary>brin_summarize_range</primary> + </indexterm> + + <indexterm> + <primary>brin_desummarize_range</primary> + </indexterm> + <para> <xref linkend="functions-admin-index-table"> shows the functions available for index maintenance tasks. @@ -19175,13 +19856,27 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); <tbody> <row> <entry> - <literal><function>brin_summarize_new_values(<parameter>index_oid</> <type>regclass</>)</function></literal> + <literal><function>brin_summarize_new_values(<parameter>index</> <type>regclass</>)</function></literal> </entry> <entry><type>integer</type></entry> <entry>summarize page ranges not already summarized</entry> </row> <row> <entry> + <literal><function>brin_summarize_range(<parameter>index</> <type>regclass</>, <parameter>blockNumber</> <type>bigint</type>)</function></literal> + </entry> + <entry><type>integer</type></entry> + <entry>summarize the page range covering the given block, if not already summarized</entry> + </row> + <row> + <entry> + <literal><function>brin_desummarize_range(<parameter>index</> <type>regclass</>, <parameter>blockNumber</> <type>bigint</type>)</function></literal> + </entry> + <entry><type>integer</type></entry> + <entry>de-summarize the page range covering the given block, if summarized</entry> + </row> + <row> + <entry> <literal><function>gin_clean_pending_list(<parameter>index</> <type>regclass</>)</function></literal> </entry> <entry><type>bigint</type></entry> @@ -19192,22 +19887,23 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); </table> <para> - <function>brin_summarize_new_values</> receives a BRIN index OID as - argument and inspects the index to find page ranges in the base table + <function>brin_summarize_new_values</> accepts the OID or name of a + BRIN index and inspects the index to find page ranges in the base table that are not currently summarized by the index; for any such range it creates a new summary index tuple by scanning the table pages. It returns the number of new page range summaries that were inserted - into the index. + into the index. <function>brin_summarize_range</> does the same, except + it only summarizes the range that covers the given block number. </para> <para> <function>gin_clean_pending_list</> accepts the OID or name of - a GIN index and cleans up the pending list of the specified GIN index + a GIN index and cleans up the pending list of the specified index by moving entries in it to the main GIN data structure in bulk. - It returns the number of pages cleaned up from the pending list. - Note that if the argument is a GIN index built with <literal>fastupdate</> - option disabled, the cleanup does not happen and the return value is 0 - because the index doesn't have a pending list. + It returns the number of pages removed from the pending list. + Note that if the argument is a GIN index built with + the <literal>fastupdate</> option disabled, no cleanup happens and the + return value is 0, because the index doesn't have a pending list. Please see <xref linkend="gin-fast-update"> and <xref linkend="gin-tips"> for details of the pending list and <literal>fastupdate</> option. </para> @@ -19224,7 +19920,8 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); database cluster directory and the <varname>log_directory</> can be accessed. Use a relative path for files in the cluster directory, and a path matching the <varname>log_directory</> configuration setting - for log files. Use of these functions is restricted to superusers. + for log files. Use of these functions is restricted to superusers + except where stated otherwise. </para> <table id="functions-admin-genfile-table"> @@ -19247,6 +19944,28 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); </row> <row> <entry> + <literal><function>pg_ls_logdir()</function></literal> + </entry> + <entry><type>setof record</type></entry> + <entry> + List the name, size, and last modification time of files in the log + directory. Access is granted to members of the <literal>pg_monitor</> + role and may be granted to other non-superuser roles. + </entry> + </row> + <row> + <entry> + <literal><function>pg_ls_waldir()</function></literal> + </entry> + <entry><type>setof record</type></entry> + <entry> + List the name, size, and last modification time of files in the WAL + directory. Access is granted to members of the <literal>pg_monitor</> + role and may be granted to other non-superuser roles. + </entry> + </row> + <row> + <entry> <literal><function>pg_read_file(<parameter>filename</> <type>text</> [, <parameter>offset</> <type>bigint</>, <parameter>length</> <type>bigint</> [, <parameter>missing_ok</> <type>boolean</>] ])</function></literal> </entry> <entry><type>text</type></entry> @@ -19277,7 +19996,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); </table> <para> - All of these functions take an optional <parameter>missing_ok</> parameter, + Some of these functions take an optional <parameter>missing_ok</> parameter, which specifies the behavior when the file or directory does not exist. If <literal>true</literal>, the function returns NULL (except <function>pg_ls_dir</>, which returns an empty result set). If @@ -19298,6 +20017,27 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); </para> <indexterm> + <primary>pg_ls_logdir</primary> + </indexterm> + <para> + <function>pg_ls_logdir</> returns the name, size, and last modified time + (mtime) of each file in the log directory. By default, only superusers + and members of the <literal>pg_monitor</> role can use this function. + Access may be granted to others using <command>GRANT</command>. + </para> + + <indexterm> + <primary>pg_ls_waldir</primary> + </indexterm> + <para> + <function>pg_ls_waldir</> returns the name, size, and last modified time + (mtime) of each file in the write ahead log (WAL) directory. By + default only superusers and members of the <literal>pg_monitor</> role + can use this function. Access may be granted to others using + <command>GRANT</command>. + </para> + + <indexterm> <primary>pg_read_file</primary> </indexterm> <para> diff --git a/doc/src/sgml/generate-errcodes-table.pl b/doc/src/sgml/generate-errcodes-table.pl index 2195e0f453..01fc6166bf 100644 --- a/doc/src/sgml/generate-errcodes-table.pl +++ b/doc/src/sgml/generate-errcodes-table.pl @@ -1,7 +1,7 @@ #!/usr/bin/perl # # Generate the errcodes-table.sgml file from errcodes.txt -# Copyright (c) 2000-2016, PostgreSQL Global Development Group +# Copyright (c) 2000-2017, PostgreSQL Global Development Group use warnings; use strict; @@ -9,7 +9,7 @@ use strict; print "<!-- autogenerated from src/backend/utils/errcodes.txt, do not edit -->\n"; -open my $errcodes, $ARGV[0] or die; +open my $errcodes, '<', $ARGV[0] or die; while (<$errcodes>) { diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml index 05d92eb975..7c2321ec3c 100644 --- a/doc/src/sgml/gin.sgml +++ b/doc/src/sgml/gin.sgml @@ -85,298 +85,8 @@ </thead> <tbody> <row> - <entry><literal>_abstime_ops</></entry> - <entry><type>abstime[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_bit_ops</></entry> - <entry><type>bit[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_bool_ops</></entry> - <entry><type>boolean[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_bpchar_ops</></entry> - <entry><type>character[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_bytea_ops</></entry> - <entry><type>bytea[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_char_ops</></entry> - <entry><type>"char"[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_cidr_ops</></entry> - <entry><type>cidr[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_date_ops</></entry> - <entry><type>date[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_float4_ops</></entry> - <entry><type>float4[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_float8_ops</></entry> - <entry><type>float8[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_inet_ops</></entry> - <entry><type>inet[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_int2_ops</></entry> - <entry><type>smallint[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_int4_ops</></entry> - <entry><type>integer[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_int8_ops</></entry> - <entry><type>bigint[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_interval_ops</></entry> - <entry><type>interval[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_macaddr_ops</></entry> - <entry><type>macaddr[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_money_ops</></entry> - <entry><type>money[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_name_ops</></entry> - <entry><type>name[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_numeric_ops</></entry> - <entry><type>numeric[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_oid_ops</></entry> - <entry><type>oid[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_oidvector_ops</></entry> - <entry><type>oidvector[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_reltime_ops</></entry> - <entry><type>reltime[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_text_ops</></entry> - <entry><type>text[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_time_ops</></entry> - <entry><type>time[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_timestamp_ops</></entry> - <entry><type>timestamp[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_timestamptz_ops</></entry> - <entry><type>timestamp with time zone[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_timetz_ops</></entry> - <entry><type>time with time zone[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_tinterval_ops</></entry> - <entry><type>tinterval[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_varbit_ops</></entry> - <entry><type>bit varying[]</></entry> - <entry> - <literal>&&</> - <literal><@</> - <literal>=</> - <literal>@></> - </entry> - </row> - <row> - <entry><literal>_varchar_ops</></entry> - <entry><type>character varying[]</></entry> + <entry><literal>array_ops</></entry> + <entry><type>anyarray</></entry> <entry> <literal>&&</> <literal><@</> @@ -441,22 +151,10 @@ </para> <para> - There are three methods that an operator class for + There are two methods that an operator class for <acronym>GIN</acronym> must provide: - <variablelist> - <varlistentry> - <term><function>int compare(Datum a, Datum b)</></term> - <listitem> - <para> - Compares two keys (not indexed items!) and returns an integer less than - zero, zero, or greater than zero, indicating whether the first key is - less than, equal to, or greater than the second. Null keys are never - passed to this function. - </para> - </listitem> - </varlistentry> - + <variablelist> <varlistentry> <term><function>Datum *extractValue(Datum itemValue, int32 *nkeys, bool **nullFlags)</></term> @@ -645,7 +343,38 @@ </listitem> </varlistentry> </variablelist> + </para> + + <para> + In addition, GIN must have a way to sort the key values stored in the index. + The operator class can define the sort ordering by specifying a comparison + method: + <variablelist> + <varlistentry> + <term><function>int compare(Datum a, Datum b)</></term> + <listitem> + <para> + Compares two keys (not indexed items!) and returns an integer less than + zero, zero, or greater than zero, indicating whether the first key is + less than, equal to, or greater than the second. Null keys are never + passed to this function. + </para> + </listitem> + </varlistentry> + </variablelist> + + Alternatively, if the operator class does not provide a <function>compare</> + method, GIN will look up the default btree operator class for the index + key data type, and use its comparison function. It is recommended to + specify the comparison function in a GIN operator class that is meant for + just one data type, as looking up the btree operator class costs a few + cycles. However, polymorphic GIN operator classes (such + as <literal>array_ops</>) typically cannot specify a single comparison + function. + </para> + + <para> Optionally, an operator class for <acronym>GIN</acronym> can supply the following method: @@ -900,11 +629,9 @@ <title>Examples</title> <para> - The <productname>PostgreSQL</productname> source distribution includes - <acronym>GIN</acronym> operator classes for <type>tsvector</> and - for one-dimensional arrays of all internal types. Prefix searching in - <type>tsvector</> is implemented using the <acronym>GIN</> partial match - feature. + The core <productname>PostgreSQL</> distribution + includes the <acronym>GIN</acronym> operator classes previously shown in + <xref linkend="gin-builtin-opclasses-table">. The following <filename>contrib</> modules also contain <acronym>GIN</acronym> operator classes: diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index cc933a1744..48d5525b92 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -76,9 +76,7 @@ <para> The remainder of this section outlines various failover, replication, - and load balancing solutions. A <ulink - url="http://www.postgres-r.org/documentation/terms">glossary</ulink> is - also available. + and load balancing solutions. </para> <sect1 id="different-replication-solutions"> @@ -140,7 +138,7 @@ protocol to make nodes agree on a serializable transactional order. </varlistentry> <varlistentry> - <term>Transaction Log Shipping</term> + <term>Write-Ahead Log Shipping</term> <listitem> <para> @@ -209,7 +207,7 @@ protocol to make nodes agree on a serializable transactional order. middleware. Care must also be taken that all transactions either commit or abort on all servers, perhaps using two-phase commit (<xref linkend="sql-prepare-transaction"> - and <xref linkend="sql-commit-prepared">. + and <xref linkend="sql-commit-prepared">). <productname>Pgpool-II</> and <productname>Continuent Tungsten</> are examples of this type of replication. </para> @@ -291,7 +289,7 @@ protocol to make nodes agree on a serializable transactional order. <entry>Feature</entry> <entry>Shared Disk Failover</entry> <entry>File System Replication</entry> - <entry>Transaction Log Shipping</entry> + <entry>Write-Ahead Log Shipping</entry> <entry>Trigger-Based Master-Standby Replication</entry> <entry>Statement-Based Replication Middleware</entry> <entry>Asynchronous Multimaster Replication</entry> @@ -594,24 +592,24 @@ protocol to make nodes agree on a serializable transactional order. (see <xref linkend="restore-command">) or directly from the master over a TCP connection (streaming replication). The standby server will also attempt to restore any WAL found in the standby cluster's - <filename>pg_xlog</> directory. That typically happens after a server + <filename>pg_wal</> directory. That typically happens after a server restart, when the standby replays again WAL that was streamed from the master before the restart, but you can also manually copy files to - <filename>pg_xlog</> at any time to have them replayed. + <filename>pg_wal</> at any time to have them replayed. </para> <para> At startup, the standby begins by restoring all WAL available in the archive location, calling <varname>restore_command</>. Once it reaches the end of WAL available there and <varname>restore_command</> - fails, it tries to restore any WAL available in the <filename>pg_xlog</> directory. + fails, it tries to restore any WAL available in the <filename>pg_wal</> directory. If that fails, and streaming replication has been configured, the standby tries to connect to the primary server and start streaming WAL - from the last valid record found in archive or <filename>pg_xlog</>. If that fails + from the last valid record found in archive or <filename>pg_wal</>. If that fails or streaming replication is not configured, or if the connection is later disconnected, the standby goes back to step 1 and tries to restore the file from the archive again. This loop of retries from the - archive, <filename>pg_xlog</>, and via streaming replication goes on until the server + archive, <filename>pg_wal</>, and via streaming replication goes on until the server is stopped or failover is triggered by a trigger file. </para> @@ -619,7 +617,7 @@ protocol to make nodes agree on a serializable transactional order. Standby mode is exited and the server switches to normal operation when <command>pg_ctl promote</> is run or a trigger file is found (<varname>trigger_file</>). Before failover, - any WAL immediately available in the archive or in <filename>pg_xlog</> will be + any WAL immediately available in the archive or in <filename>pg_wal</> will be restored, but no attempt is made to connect to the master. </para> </sect2> @@ -852,9 +850,9 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' of WAL records generated in the primary, but not yet applied in the standby. You can calculate this lag by comparing the current WAL write location on the primary with the last WAL location received by the - standby. They can be retrieved using - <function>pg_current_xlog_location</> on the primary and the - <function>pg_last_xlog_receive_location</> on the standby, + standby. These locations can be retrieved using + <function>pg_current_wal_lsn</> on the primary and + <function>pg_last_wal_receive_lsn</> on the standby, respectively (see <xref linkend="functions-admin-backup-table"> and <xref linkend="functions-recovery-info-table"> for details). The last WAL receive location in the standby is also displayed in the @@ -865,10 +863,10 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' You can retrieve a list of WAL sender processes via the <link linkend="monitoring-stats-views-table"> <literal>pg_stat_replication</></link> view. Large differences between - <function>pg_current_xlog_location</> and <literal>sent_location</> field + <function>pg_current_wal_lsn</> and the view's <literal>sent_lsn</> field might indicate that the master server is under heavy load, while - differences between <literal>sent_location</> and - <function>pg_last_xlog_receive_location</> on the standby might indicate + differences between <literal>sent_lsn</> and + <function>pg_last_wal_receive_lsn</> on the standby might indicate network delay, or that the standby is under heavy load. </para> </sect3> @@ -895,7 +893,7 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' However, these methods often result in retaining more WAL segments than required, whereas replication slots retain only the number of segments known to be needed. An advantage of these methods is that they bound - the space requirement for <literal>pg_xlog</>; there is currently no way + the space requirement for <literal>pg_wal</>; there is currently no way to do this using replication slots. </para> <para> @@ -929,8 +927,8 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' You can create a replication slot like this: <programlisting> postgres=# SELECT * FROM pg_create_physical_replication_slot('node_a_slot'); - slot_name | xlog_position --------------+--------------- + slot_name | lsn +-------------+----- node_a_slot | postgres=# SELECT * FROM pg_replication_slots; @@ -1038,7 +1036,7 @@ primary_slot_name = 'node_a_slot' <para> When requesting synchronous replication, each commit of a write transaction will wait until confirmation is - received that the commit has been written to the transaction log on disk + received that the commit has been written to the write-ahead log on disk of both the primary and standby server. The only possibility that data can be lost is if both the primary and the standby suffer crashes at the same time. This can provide a much higher level of durability, though only @@ -1086,8 +1084,8 @@ primary_slot_name = 'node_a_slot' In the case that <varname>synchronous_commit</> is set to <literal>remote_apply</>, the standby sends reply messages when the commit record is replayed, making the transaction visible. - If the standby is chosen as a synchronous standby, from a priority - list of <varname>synchronous_standby_names</> on the primary, the reply + If the standby is chosen as a synchronous standby, according to the setting + of <varname>synchronous_standby_names</> on the primary, the reply messages from that standby will be considered along with those from other synchronous standbys to decide when to release transactions waiting for confirmation that the commit record has been received. These parameters @@ -1138,19 +1136,25 @@ primary_slot_name = 'node_a_slot' as synchronous confirm receipt of their data. The number of synchronous standbys that transactions must wait for replies from is specified in <varname>synchronous_standby_names</>. This parameter also specifies - a list of standby names, which determines the priority of each standby - for being chosen as a synchronous standby. The standbys whose names - appear earlier in the list are given higher priority and will be considered - as synchronous. Other standby servers appearing later in this list - represent potential synchronous standbys. If any of the current - synchronous standbys disconnects for whatever reason, it will be replaced - immediately with the next-highest-priority standby. + a list of standby names and the method (<literal>FIRST</> and + <literal>ANY</>) to choose synchronous standbys from the listed ones. </para> <para> - An example of <varname>synchronous_standby_names</> for multiple - synchronous standbys is: + The method <literal>FIRST</> specifies a priority-based synchronous + replication and makes transaction commits wait until their WAL records are + replicated to the requested number of synchronous standbys chosen based on + their priorities. The standbys whose names appear earlier in the list are + given higher priority and will be considered as synchronous. Other standby + servers appearing later in this list represent potential synchronous + standbys. If any of the current synchronous standbys disconnects for + whatever reason, it will be replaced immediately with the + next-highest-priority standby. + </para> + <para> + An example of <varname>synchronous_standby_names</> for + a priority-based multiple synchronous standbys is: <programlisting> -synchronous_standby_names = '2 (s1, s2, s3)' +synchronous_standby_names = 'FIRST 2 (s1, s2, s3)' </programlisting> In this example, if four standby servers <literal>s1</>, <literal>s2</>, <literal>s3</> and <literal>s4</> are running, the two standbys @@ -1161,6 +1165,28 @@ synchronous_standby_names = '2 (s1, s2, s3)' <literal>s2</> fails. <literal>s4</> is an asynchronous standby since its name is not in the list. </para> + <para> + The method <literal>ANY</> specifies a quorum-based synchronous + replication and makes transaction commits wait until their WAL records + are replicated to <emphasis>at least</> the requested number of + synchronous standbys in the list. + </para> + <para> + An example of <varname>synchronous_standby_names</> for + a quorum-based multiple synchronous standbys is: +<programlisting> + synchronous_standby_names = 'ANY 2 (s1, s2, s3)' +</programlisting> + In this example, if four standby servers <literal>s1</>, <literal>s2</>, + <literal>s3</> and <literal>s4</> are running, transaction commits will + wait for replies from at least any two standbys of <literal>s1</>, + <literal>s2</> and <literal>s3</>. <literal>s4</> is an asynchronous + standby since its name is not in the list. + </para> + <para> + The synchronous states of standby servers can be viewed using + the <structname>pg_stat_replication</structname> view. + </para> </sect3> <sect3 id="synchronous-replication-performance"> @@ -1220,9 +1246,20 @@ synchronous_standby_names = '2 (s1, s2, s3)' The best solution for high availability is to ensure you keep as many synchronous standbys as requested. This can be achieved by naming multiple potential synchronous standbys using <varname>synchronous_standby_names</>. - The standbys whose names appear earlier in the list will be used as - synchronous standbys. Standbys listed after these will take over - the role of synchronous standby if one of current ones should fail. + </para> + + <para> + In a priority-based synchronous replication, the standbys whose names + appear earlier in the list will be used as synchronous standbys. + Standbys listed after these will take over the role of synchronous standby + if one of current ones should fail. + </para> + + <para> + In a quorum-based synchronous replication, all the standbys appearing + in the list will be used as candidates for synchronous standbys. + Even if one of them should fail, the other standbys will keep performing + the role of candidates of synchronous standby. </para> <para> @@ -1235,6 +1272,8 @@ synchronous_standby_names = '2 (s1, s2, s3)' will increase according to the length of time the standby has been down. The standby is only able to become a synchronous standby once it has reached <literal>streaming</> state. + This state can be viewed using + the <structname>pg_stat_replication</structname> view. </para> <para> @@ -1557,7 +1596,7 @@ if (!triggered) </para> <para> - An external program can call the <function>pg_xlogfile_name_offset()</> + An external program can call the <function>pg_walfile_name_offset()</> function (see <xref linkend="functions-admin">) to find out the file name and the exact byte offset within it of the current end of WAL. It can then access the WAL file directly @@ -2023,8 +2062,8 @@ if (!triggered) <title>Administrator's Overview</title> <para> - If <varname>hot_standby</> is turned <literal>on</> in - <filename>postgresql.conf</> and there is a <filename>recovery.conf</> + If <varname>hot_standby</> is <literal>on</> in <filename>postgresql.conf</> + (the default value) and there is a <filename>recovery.conf</> file present, the server will run in Hot Standby mode. However, it may take some time for Hot Standby connections to be allowed, because the server will not accept connections until it has completed @@ -2200,7 +2239,7 @@ LOG: database system is ready to accept read only connections <para> WAL file control commands will not work during recovery, - e.g. <function>pg_start_backup</>, <function>pg_switch_xlog</> etc. + e.g. <function>pg_start_backup</>, <function>pg_switch_wal</> etc. </para> <para> @@ -2328,12 +2367,6 @@ LOG: database system is ready to accept read only connections <itemizedlist> <listitem> <para> - Operations on hash indexes are not presently WAL-logged, so - replay will not update these indexes. - </para> - </listitem> - <listitem> - <para> Full knowledge of running transactions is required before snapshots can be taken. Transactions that use large numbers of subtransactions (currently greater than 64) will delay the start of read only diff --git a/doc/src/sgml/indexam.sgml b/doc/src/sgml/indexam.sgml index b59cd0363a..ac512588e2 100644 --- a/doc/src/sgml/indexam.sgml +++ b/doc/src/sgml/indexam.sgml @@ -51,16 +51,9 @@ <link linkend="catalog-pg-am"><structname>pg_am</structname></link> system catalog. The <structname>pg_am</structname> entry specifies a name and a <firstterm>handler function</> for the access - method. There is not currently any special support - for creating or deleting <structname>pg_am</structname> entries; - anyone able to write a new access method is expected to be competent - to insert an appropriate row for themselves. - </para> - - <para> - Index access methods can be defined and dropped using + method. These entries can be created and deleted using the <xref linkend="sql-create-access-method"> and - <xref linkend="sql-drop-access-method"> SQL commands respectively. + <xref linkend="sql-drop-access-method"> SQL commands. </para> <para> @@ -117,6 +110,8 @@ typedef struct IndexAmRoutine bool amclusterable; /* does AM handle predicate locks? */ bool ampredlocks; + /* does AM support parallel scan? */ + bool amcanparallel; /* type of data stored in index, or InvalidOid if variable */ Oid amkeytype; @@ -138,6 +133,11 @@ typedef struct IndexAmRoutine amendscan_function amendscan; ammarkpos_function ammarkpos; /* can be NULL */ amrestrpos_function amrestrpos; /* can be NULL */ + + /* interface functions to support parallel index scans */ + amestimateparallelscan_function amestimateparallelscan; /* can be NULL */ + aminitparallelscan_function aminitparallelscan; /* can be NULL */ + amparallelrescan_function amparallelrescan; /* can be NULL */ } IndexAmRoutine; </programlisting> </para> @@ -261,7 +261,8 @@ aminsert (Relation indexRelation, bool *isnull, ItemPointer heap_tid, Relation heapRelation, - IndexUniqueCheck checkUnique); + IndexUniqueCheck checkUnique, + IndexInfo *indexInfo); </programlisting> Insert a new tuple into an existing index. The <literal>values</> and <literal>isnull</> arrays give the key values to be indexed, and @@ -290,6 +291,14 @@ aminsert (Relation indexRelation, </para> <para> + If the index AM wishes to cache data across successive index insertions + within a SQL statement, it can allocate space + in <literal>indexInfo->ii_Context</literal> and store a pointer to the + data in <literal>indexInfo->ii_AmCache</literal> (which will be NULL + initially). + </para> + + <para> <programlisting> IndexBulkDeleteResult * ambulkdelete (IndexVacuumInfo *info, @@ -542,15 +551,19 @@ amgettuple (IndexScanDesc scan, <para> If the index supports <link linkend="indexes-index-only-scans">index-only scans</link> (i.e., <function>amcanreturn</function> returns TRUE for it), - then on success the AM must also check - <literal>scan->xs_want_itup</>, and if that is true it must return - the original indexed data for the index entry, in the form of an + then on success the AM must also check <literal>scan->xs_want_itup</>, + and if that is true it must return the originally indexed data for the + index entry. The data can be returned in the form of an <structname>IndexTuple</> pointer stored at <literal>scan->xs_itup</>, - with tuple descriptor <literal>scan->xs_itupdesc</>. - (Management of the data referenced by the pointer is the access method's + with tuple descriptor <literal>scan->xs_itupdesc</>; or in the form of + a <structname>HeapTuple</> pointer stored at <literal>scan->xs_hitup</>, + with tuple descriptor <literal>scan->xs_hitupdesc</>. (The latter + format should be used when reconstructing data that might possibly not fit + into an IndexTuple.) In either case, + management of the data referenced by the pointer is the access method's responsibility. The data must remain good at least until the next <function>amgettuple</>, <function>amrescan</>, or <function>amendscan</> - call for the scan.) + call for the scan. </para> <para> @@ -631,6 +644,68 @@ amrestrpos (IndexScanDesc scan); the <structfield>amrestrpos</> field in its <structname>IndexAmRoutine</> struct may be set to NULL. </para> + + <para> + In addition to supporting ordinary index scans, some types of index + may wish to support <firstterm>parallel index scans</>, which allow + multiple backends to cooperate in performing an index scan. The + index access method should arrange things so that each cooperating + process returns a subset of the tuples that would be performed by + an ordinary, non-parallel index scan, but in such a way that the + union of those subsets is equal to the set of tuples that would be + returned by an ordinary, non-parallel index scan. Furthermore, while + there need not be any global ordering of tuples returned by a parallel + scan, the ordering of that subset of tuples returned within each + cooperating backend must match the requested ordering. The following + functions may be implemented to support parallel index scans: + </para> + + <para> +<programlisting> +Size +amestimateparallelscan (void); +</programlisting> + Estimate and return the number of bytes of dynamic shared memory which + the access method will be needed to perform a parallel scan. (This number + is in addition to, not in lieu of, the amount of space needed for + AM-independent data in <structname>ParallelIndexScanDescData</>.) + </para> + + <para> + It is not necessary to implement this function for access methods which + do not support parallel scans or for which the number of additional bytes + of storage required is zero. + </para> + + <para> +<programlisting> +void +aminitparallelscan (void *target); +</programlisting> + This function will be called to initialize dynamic shared memory at the + beginning of a parallel scan. <parameter>target</> will point to at least + the number of bytes previously returned by + <function>amestimateparallelscan</>, and this function may use that + amount of space to store whatever data it wishes. + </para> + + <para> + It is not necessary to implement this function for access methods which + do not support parallel scans or in cases where the shared memory space + required needs no initialization. + </para> + + <para> +<programlisting> +void +amparallelrescan (IndexScanDesc scan); +</programlisting> + This function, if implemented, will be called when a parallel index scan + must be restarted. It should reset any shared state set up by + <function>aminitparallelscan</> such that the scan will be restarted from + the beginning. + </para> + </sect1> <sect1 id="index-scanning"> diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml index 824e904e53..af3f284e97 100644 --- a/doc/src/sgml/indices.sgml +++ b/doc/src/sgml/indices.sgml @@ -199,18 +199,6 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable> </synopsis> </para> - <caution> - <para> - Hash index operations are not presently WAL-logged, - so hash indexes might need to be rebuilt with <command>REINDEX</> - after a database crash if there were unwritten changes. - Also, changes to hash indexes are not replicated over streaming or - file-based replication after the initial base backup, so they - give wrong answers to queries that subsequently use them. - For these reasons, hash index use is presently discouraged. - </para> - </caution> - <para> <indexterm> <primary>index</primary> @@ -321,9 +309,8 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10; operators with which a GIN index can be used vary depending on the indexing strategy. As an example, the standard distribution of - <productname>PostgreSQL</productname> includes GIN operator classes - for one-dimensional arrays, which support indexed - queries using these operators: + <productname>PostgreSQL</productname> includes a GIN operator class + for arrays, which supports indexed queries using these operators: <simplelist> <member><literal><@</literal></member> diff --git a/doc/src/sgml/info.sgml b/doc/src/sgml/info.sgml index b1738a75a7..4e5503c3c6 100644 --- a/doc/src/sgml/info.sgml +++ b/doc/src/sgml/info.sgml @@ -10,11 +10,25 @@ <variablelist> <varlistentry> + <term>Wiki</term> + <listitem> + <para> + The <productname>PostgreSQL</productname> <ulink + url="https://wiki.postgresql.org">wiki</ulink> contains the project's <ulink + url="https://wiki.postgresql.org/wiki/Frequently_Asked_Questions">FAQ</> + (Frequently Asked Questions) list, <ulink + url="https://wiki.postgresql.org/wiki/Todo">TODO</> list, and + detailed information about many more topics. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term>Web Site</term> <listitem> <para> - The <productname>Postgres-XL</productname> - <ulink url="http://www.postgres-xl.org/">web site</ulink> + The <productname>Postgres-XL</productname> + <ulink url="http://www.postgres-xl.org">web site</ulink> carries details on the latest release and other information to make your work or play with <productname>Postgres-XL</productname> more productive. diff --git a/doc/src/sgml/information_schema.sgml b/doc/src/sgml/information_schema.sgml index c43e325d06..02f7927436 100644 --- a/doc/src/sgml/information_schema.sgml +++ b/doc/src/sgml/information_schema.sgml @@ -1583,13 +1583,20 @@ <row> <entry><literal>is_identity</literal></entry> <entry><type>yes_or_no</type></entry> - <entry>Applies to a feature not available in <productname>PostgreSQL</></entry> + <entry> + If the column is an identity column, then <literal>YES</literal>, + else <literal>NO</literal>. + </entry> </row> <row> <entry><literal>identity_generation</literal></entry> <entry><type>character_data</type></entry> - <entry>Applies to a feature not available in <productname>PostgreSQL</></entry> + <entry> + If the column is an identity column, then <literal>ALWAYS</literal> + or <literal>BY DEFAULT</literal>, reflecting the definition of the + column. + </entry> </row> <row> @@ -4653,9 +4660,7 @@ ORDER BY c.ordinal_position; <entry><literal>data_type</literal></entry> <entry><type>character_data</type></entry> <entry> - The data type of the sequence. In - <productname>PostgreSQL</productname>, this is currently always - <literal>bigint</literal>. + The data type of the sequence. </entry> </row> diff --git a/doc/src/sgml/install-windows.sgml b/doc/src/sgml/install-windows.sgml index 8cd189c8e1..f5dfb91ac1 100644 --- a/doc/src/sgml/install-windows.sgml +++ b/doc/src/sgml/install-windows.sgml @@ -35,14 +35,6 @@ </para> <para> - Finally, the client access library - (<application>libpq</application>) can be built using - <productname>Visual C++ 7.1</productname> or - <productname>Borland C++</productname> for compatibility with statically - linked applications built using these tools. - </para> - - <para> Building using <productname>MinGW</productname> or <productname>Cygwin</productname> uses the normal build system, see <xref linkend="installation"> and the specific notes in @@ -51,7 +43,7 @@ <productname>MinGW-w64</productname>. These tools can also be used to cross-compile for 32 bit and 64 bit <productname>Windows</productname> targets on other hosts, such as <productname>Linux</productname> and - <productname>Darwin</productname>. + <productname>macOS</productname>. <productname>Cygwin</productname> is not recommended for running a production server, and it should only be used for running on older versions of <productname>Windows</productname> where @@ -145,6 +137,14 @@ $ENV{PATH}=$ENV{PATH} . ';c:\some\where\bison\bin'; </programlisting> </para> + <para> + To pass additional command line arguments to the Visual Studio build + command (msbuild or vcbuild): +<programlisting> +$ENV{MSBFLAGS}="/m"; +</programlisting> + </para> + <sect2> <title>Requirements</title> <para> @@ -161,7 +161,7 @@ $ENV{PATH}=$ENV{PATH} . ';c:\some\where\bison\bin'; <productname>Microsoft Windows SDK</productname> it is recommended that you upgrade to the latest version (currently version 7.1), available for download from - <ulink url="http://www.microsoft.com/downloads/"></>. + <ulink url="https://www.microsoft.com/download"></>. </para> <para> You must always include the @@ -197,7 +197,7 @@ $ENV{PATH}=$ENV{PATH} . ';c:\some\where\bison\bin'; <varlistentry> <term><productname>ActiveState TCL</productname></term> <listitem><para> - Required for building <application>PL/TCL</application> (Note: version + Required for building <application>PL/Tcl</application> (Note: version 8.4 is required, the free Standard Distribution is sufficient). </para></listitem> </varlistentry> @@ -510,16 +510,6 @@ $ENV{PERL5LIB}=$ENV{PERL5LIB} . ';c:\IPC-Run-0.94\lib'; </varlistentry> <varlistentry> - <term>DocBook DSSSL 1.79</term> - <listitem><para> - Download from - <ulink url="http://sourceforge.net/projects/docbook/files/docbook-dsssl/1.79/docbook-dsssl-1.79.zip/download"></> - and uncompress in the subdirectory - <filename>docbook-dsssl-1.79</filename>. - </para></listitem> - </varlistentry> - - <varlistentry> <term>ISO character entities</term> <listitem><para> Download from @@ -541,113 +531,4 @@ $ENV{DOCROOT}='c:\docbook'; </sect2> </sect1> - - <sect1 id="install-windows-libpq"> - <title>Building <application>libpq</application> with - <productname>Visual C++</productname> or - <productname>Borland C++</productname></title> - - <para> - Using <productname>Visual C++ 7.1-9.0</productname> or - <productname>Borland C++</productname> to build libpq is only recommended - if you need a version with different debug/release flags, or if you need a - static library to link into an application. For normal use the - <productname>MinGW</productname> or - <productname>Visual Studio</productname> or - <productname>Windows SDK</productname> method is recommended. - </para> - - <para> - To build the <application>libpq</application> client library using - <productname>Visual Studio 7.1 or later</productname>, change into the - <filename>src</filename> directory and type the command: -<screen> -<userinput>nmake /f win32.mak</userinput> -</screen> - </para> - <para> - To build a 64-bit version of the <application>libpq</application> - client library using <productname>Visual Studio 8.0 or - later</productname>, change into the <filename>src</filename> - directory and type in the command: -<screen> -<userinput>nmake /f win32.mak CPU=AMD64</userinput> -</screen> - See the <filename>win32.mak</filename> file for further details - about supported variables. - </para> - - <para> - To build the <application>libpq</application> client library using - <productname>Borland C++</productname>, change into the - <filename>src</filename> directory and type the command: -<screen> -<userinput>make -N -DCFG=Release /f bcc32.mak</userinput> -</screen> - </para> - - <sect2> - <title>Generated Files</title> - <para> - The following files will be built: - - <variablelist> - <varlistentry> - <term><filename>interfaces\libpq\Release\libpq.dll</filename></term> - <listitem> - <para> - The dynamically linkable frontend library - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>interfaces\libpq\Release\libpqdll.lib</filename></term> - <listitem> - <para> - Import library to link your programs to <filename>libpq.dll</filename> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>interfaces\libpq\Release\libpq.lib</filename></term> - <listitem> - <para> - Static version of the frontend library - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - - <para> - Normally you do not need to install any of the client files. You should - place the <filename>libpq.dll</filename> file in the same directory - as your applications executable file. Do not install - <filename>libpq.dll</filename> into your <filename>Windows</>, - <filename>System</> or <filename>System32</> directory unless - absolutely necessary. - If this file is installed using a setup program, then it should - be installed with version checking using the - <symbol>VERSIONINFO</symbol> resource included in the file, to - ensure that a newer version of the library is not overwritten. - </para> - - <para> - If you are planning to do development using <application>libpq</application> - on this machine, you will have to add the - <filename>src\include</filename> and - <filename>src\interfaces\libpq</filename> subdirectories of the source - tree to the include path in your compiler's settings. - </para> - - <para> - To use the library, you must add the - <filename>libpqdll.lib</filename> file to your project. (In Visual - C++, just right-click on the project and choose to add it.) - </para> - </sect2> - </sect1> </chapter> diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 159ddf2e6f..b6450893b7 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -245,11 +245,7 @@ su - postgres language, you need a <productname>Python</productname> installation with the header files and the <application>distutils</application> module. The minimum - required version is <productname>Python</productname> 2.3. - (To work with function arguments of type <type>numeric</>, a 2.3.x - installation must include the separately-available <filename>cdecimal</> - module; note the <application>PL/Python</> regression tests - will not pass if that is missing.) + required version is <productname>Python</productname> 2.4. <productname>Python 3</productname> is supported if it's version 3.1 or later; but see <![%standalone-include[the <application>PL/Python</> documentation]]> @@ -304,10 +300,17 @@ su - postgres <listitem> <para> - You need <application>Kerberos</>, <productname>OpenSSL</>, - <productname>OpenLDAP</>, and/or - <application>PAM</>, if you want to support authentication or - encryption using those services. + You need <productname>OpenSSL</>, if you want to support + encrypted client connections. The minimum required version is + 0.9.8. + </para> + </listitem> + + <listitem> + <para> + You need <application>Kerberos</>, <productname>OpenLDAP</>, + and/or <application>PAM</>, if you want to support authentication + using those services. </para> </listitem> @@ -796,6 +799,21 @@ su - postgres </varlistentry> <varlistentry> + <term><option>--with-icu</option></term> + <listitem> + <para> + Build with support for + the <productname>ICU</productname><indexterm><primary>ICU</></> + library. This requires the <productname>ICU4C</productname> package + as well + as <productname>pkg-config</productname><indexterm><primary>pkg-config</></> + to be installed. The minimum required version + of <productname>ICU4C</productname> is currently 4.6. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>--with-openssl</option> <indexterm> <primary>OpenSSL</primary> @@ -899,7 +917,7 @@ su - postgres <listitem> <para> Build with Bonjour support. This requires Bonjour support - in your operating system. Recommended on OS X. + in your operating system. Recommended on macOS. </para> </listitem> </varlistentry> @@ -925,7 +943,7 @@ su - postgres <para> <option>e2fs</> to use the UUID library created by the <literal>e2fsprogs</> project; this library is present in most - Linux systems and in OS X, and can be obtained for other + Linux systems and in macOS, and can be obtained for other platforms as well </para> </listitem> @@ -985,28 +1003,6 @@ su - postgres </varlistentry> <varlistentry> - <term><option>--disable-integer-datetimes</option></term> - <listitem> - <para> - Disable support for 64-bit integer storage for timestamps and - intervals, and store datetime values as floating-point - numbers instead. Floating-point datetime storage was the - default in <productname>PostgreSQL</productname> releases - prior to 8.4, but it is now deprecated, because it does not - support microsecond precision for the full range of - <type>timestamp</type> values. However, integer-based - datetime storage requires a 64-bit integer type. Therefore, - this option can be used when no such type is available, or - for compatibility with applications written for prior - versions of <productname>PostgreSQL</productname>. See - <![%standalone-include[the documentation about datetime datatypes]]> - <![%standalone-ignore[<xref linkend="datatype-datetime">]]> - for more information. - </para> - </listitem> - </varlistentry> - - <varlistentry> <term><option>--disable-float4-byval</option></term> <listitem> <para> @@ -1085,7 +1081,7 @@ su - postgres the size of each individual file in the WAL log. It may be useful to adjust this size to control the granularity of WAL log shipping. The default size is 16 megabytes. - The value must be a power of 2 between 1 and 64 (megabytes). + The value must be a power of 2 between 1 and 1024 (megabytes). Note that changing this value requires an initdb. </para> </listitem> @@ -1122,6 +1118,25 @@ su - postgres </varlistentry> <varlistentry> + <term><option>--disable-strong-random</option></term> + <listitem> + <para> + Allow the build to succeed even if <productname>PostgreSQL</> + has no support for strong random numbers on the platform. + A source of random numbers is needed for some authentication + protocols, as well as some routines in the + <![%standalone-include[pgcrypto]]> + <![%standalone-ignore[<xref linkend="pgcrypto">]]> + module. <option>--disable-strong-random</option> disables functionality that + requires cryptographically strong random numbers, and substitutes + a weak pseudo-random-number-generator for the generation of + authentication salt values and query cancel keys. It may make + authentication less secure. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>--disable-thread-safety</option></term> <listitem> <para> @@ -1454,7 +1469,7 @@ su - postgres <term><envar>PERL</envar></term> <listitem> <para> - Full path to the Perl interpreter. This will be used to + Full path name of the Perl interpreter. This will be used to determine the dependencies for building PL/Perl. </para> </listitem> @@ -1464,7 +1479,7 @@ su - postgres <term><envar>PYTHON</envar></term> <listitem> <para> - Full path to the Python interpreter. This will be used to + Full path name of the Python interpreter. This will be used to determine the dependencies for building PL/Python. Also, whether Python 2 or 3 is specified here (or otherwise implicitly chosen) determines which variant of the PL/Python @@ -1481,7 +1496,7 @@ su - postgres <term><envar>TCLSH</envar></term> <listitem> <para> - Full path to the Tcl interpreter. This will be used to + Full path name of the Tcl interpreter. This will be used to determine the dependencies for building PL/Tcl, and it will be substituted into Tcl scripts. </para> @@ -1500,6 +1515,26 @@ su - postgres </variablelist> </para> + <para> + Sometimes it is useful to add compiler flags after-the-fact to the set + that were chosen by <filename>configure</>. An important example is + that <application>gcc</>'s <option>-Werror</> option cannot be included + in the <envar>CFLAGS</envar> passed to <filename>configure</>, because + it will break many of <filename>configure</>'s built-in tests. To add + such flags, include them in the <envar>COPT</envar> environment variable + while running <filename>make</>. The contents of <envar>COPT</envar> + are added to both the <envar>CFLAGS</envar> and <envar>LDFLAGS</envar> + options set up by <filename>configure</>. For example, you could do +<screen> +<userinput>make COPT='-Werror'</> +</screen> + or +<screen> +<userinput>export COPT='-Werror'</> +<userinput>make</> +</screen> + </para> + <note> <para> When developing code inside the server, it is recommended to @@ -1520,6 +1555,14 @@ su - postgres <option>-O0</>. An easy way to do this is by passing an option to <application>make</>: <command>make PROFILE=-O0 file.o</>. </para> + + <para> + The <envar>COPT</> and <envar>PROFILE</> environment variables are + actually handled identically by the <productname>PostgreSQL</> + makefiles. Which to use is a matter of preference, but a common habit + among developers is to use <envar>PROFILE</> for one-time flag + adjustments, while <envar>COPT</> might be kept set all the time. + </para> </note> </step> @@ -1535,7 +1578,7 @@ su - postgres will take a few minutes depending on your hardware. The last line displayed should be: <screen> -All of PostgreSQL is successfully made. Ready to install. +All of PostgreSQL successfully made. Ready to install. </screen> </para> @@ -1548,7 +1591,7 @@ All of PostgreSQL is successfully made. Ready to install. </screen> The last line displayed should be: <screen> -PostgreSQL, contrib and HTML documentation successfully made. Ready to install. +PostgreSQL, contrib, and documentation successfully made. Ready to install. </screen> </para> </step> @@ -2688,7 +2731,7 @@ kill `cat /usr/local/pgsql/gtm-proxy/gtm_proxy.pid should take care of it. </para> - <!-- http://archives.postgresql.org/message-id/[email protected] --> + <!-- https://archives.postgresql.org/message-id/[email protected] --> <para> One user reports: @@ -2750,24 +2793,24 @@ hosts=local4,bind4 <sect3> <title>Memory Management</title> - <!-- http://archives.postgresql.org/message-id/[email protected] --> + <!-- https://archives.postgresql.org/message-id/[email protected] --> <para> AIX can be somewhat peculiar with regards to the way it does memory management. You can have a server with many multiples of gigabytes of RAM free, but still get out of memory or address space errors when running applications. One example - is <command>createlang</command> failing with unusual errors. + is loading of extensions failing with unusual errors. For example, running as the owner of the PostgreSQL installation: <screen> --bash-3.00$ createlang plperl template1 -createlang: language installation failed: ERROR: could not load library "/opt/dbs/pgsql748/lib/plperl.so": A memory address is not in the address space for the process. +=# CREATE EXTENSION plperl; +ERROR: could not load library "/opt/dbs/pgsql/lib/plperl.so": A memory address is not in the address space for the process. </screen> Running as a non-owner in the group possessing the PostgreSQL installation: <screen> --bash-3.00$ createlang plperl template1 -createlang: language installation failed: ERROR: could not load library "/opt/dbs/pgsql748/lib/plperl.so": Bad address +=# CREATE EXTENSION plperl; +ERROR: could not load library "/opt/dbs/pgsql/lib/plperl.so": Bad address </screen> Another example is out of memory errors in the PostgreSQL server logs, with every memory allocation near or greater than 256 MB @@ -2785,7 +2828,7 @@ createlang: language installation failed: ERROR: could not load library "/opt/d </para> <para> - In the case of the <command>createlang</command> example, above, + In the case of the <literal>plperl</literal> example, above, check your umask and the permissions of the binaries in your PostgreSQL installation. The binaries involved in that example were 32-bit and installed as mode 750 instead of 755. Due to the @@ -3182,167 +3225,6 @@ PHSS_30849 s700_800 u2comp/be/plugin library Patch </sect3> </sect2> - <sect2 id="installation-notes-sco"> - <title>SCO OpenServer and SCO UnixWare</title> - - <indexterm zone="installation-notes-sco"> - <primary>SCO</primary> - <secondary>installation on</secondary> - </indexterm> - - <note> - <para> - <productname>Postgres-XL</productname> has not been tested on SCO. - </para> - </note> - - - <indexterm zone="installation-notes-sco"> - <primary>UnixWare</primary> - <secondary>installation on</secondary> - </indexterm> - - <para> - PostgreSQL can be built on SCO UnixWare 7 and SCO OpenServer 5. - On OpenServer, you can use either the OpenServer Development Kit - or the Universal Development Kit. However, some tweaking may be - needed, as described below. - </para> - - <sect3> - <title>Skunkware</title> - - <para> - You should locate your copy of the SCO Skunkware CD. The - Skunkware CD is included with UnixWare 7 and current versions of - OpenServer 5. Skunkware includes ready-to-install versions of - many popular programs that are available on the Internet. For - example, gzip, gunzip, GNU Make, Flex, and Bison are all - included. For UnixWare 7.1, this CD is now labeled "Open License - Software Supplement". If you do not have this CD, the software - on it is available - from <ulink url="http://www.sco.com/skunkware/"></ulink>. - </para> - - <para> - Skunkware has different versions for UnixWare and OpenServer. - Make sure you install the correct version for your operating - system, except as noted below. - </para> - - <para> - On UnixWare 7.1.3 and beyond, the GCC compiler is included on the - UDK CD as is GNU Make. - </para> - </sect3> - - <sect3> - <title>GNU Make</title> - - <para> - You need to use the GNU Make program, which is on the Skunkware - CD. By default, it installs - as <filename>/usr/local/bin/make</filename>. - </para> - - <para> - As of UnixWare 7.1.3 and above, the GNU Make program is the - OSTK portion of the UDK CD, and is - in <filename>/usr/gnu/bin/gmake</filename>. - </para> - </sect3> - - <sect3> - <title>Readline</title> - - <para> - The Readline library is on the Skunkware CD. But it is not - included on the UnixWare 7.1 Skunkware CD. If you have the - UnixWare 7.0.0 or 7.0.1 Skunkware CDs, you can install it from - there. Otherwise, - try <ulink url="http://www.sco.com/skunkware/"></ulink>. - </para> - - <para> - By default, Readline installs into <filename>/usr/local/lib</> and - <filename>/usr/local/include</>. However, the - PostgreSQL <command>configure</command> program will not find it - there without help. If you installed Readline, then use the - following options to <command>configure</command>: -<programlisting> -./configure --with-libraries=/usr/local/lib --with-includes=/usr/local/include -</programlisting> - </para> - </sect3> - - <sect3> - <title>Using the UDK on OpenServer</title> - - <para> - If you are using the new Universal Development Kit (UDK) compiler - on OpenServer, you need to specify the locations of the UDK - libraries: -<programlisting> -./configure --with-libraries=/udk/usr/lib --with-includes=/udk/usr/include -</programlisting> - Putting these together with the Readline options from above: -<programlisting> -./configure --with-libraries="/udk/usr/lib /usr/local/lib" --with-includes="/udk/usr/include /usr/local/include" -</programlisting> - </para> - </sect3> - - <sect3> - <title>Reading the PostgreSQL Man Pages</title> - - <para> - By default, the PostgreSQL man pages are installed into - <filename>/usr/local/pgsql/share/man</filename>. By default, UnixWare - does not look there for man pages. To be able to read them you - need to modify the - <varname>MANPATH</varname> variable - in <filename>/etc/default/man</filename>, for example: -<programlisting> -MANPATH=/usr/lib/scohelp/%L/man:/usr/dt/man:/usr/man:/usr/share/man:scohelp:/usr/local/man:/usr/local/pgsql/share/man -</programlisting> - </para> - - <para> - On OpenServer, some extra research needs to be invested to make - the man pages usable, because the man system is a bit different - from other platforms. Currently, PostgreSQL will not install - them at all. - </para> - </sect3> - - <sect3> - <title>C99 Issues with the 7.1.1b Feature Supplement</title> - - <para> - For compilers earlier than the one released with OpenUNIX 8.0.0 - (UnixWare 7.1.2), including the 7.1.1b Feature Supplement, you - may need to specify <option>-Xb</option> - in <varname>CFLAGS</varname> or the <varname>CC</varname> - environment variable. The indication of this is an error in - compiling <filename>tuplesort.c</filename> referencing inline - functions. Apparently there was a change in the 7.1.2(8.0.0) - compiler and beyond. - </para> - </sect3> - - <sect3> - <title>Threading on UnixWare</title> - - <para> - For threading, you<emphasis>must</emphasis> use <option>-Kpthread</option> - on <emphasis>all</emphasis> libpq-using programs. libpq - uses <function>pthread_*</function> calls, which are only - available with the - <option>-Kpthread</>/<option>-Kthread</> flag. - </para> - </sect3> - </sect2> - <sect2 id="installation-notes-solaris"> <title>Solaris</title> @@ -3391,30 +3273,6 @@ MANPATH=/usr/lib/scohelp/%L/man:/usr/dt/man:/usr/man:/usr/share/man:scohelp:/usr </sect3> <sect3> - <title>Problems with OpenSSL</title> - - <para> - When you build PostgreSQL with OpenSSL support you might get - compilation errors in the following files: - <itemizedlist> - <listitem><para><filename>src/backend/libpq/crypt.c</filename></para></listitem> - <listitem><para><filename>src/backend/libpq/password.c</filename></para></listitem> - <listitem><para><filename>src/interfaces/libpq/fe-auth.c</filename></para></listitem> - <listitem><para><filename>src/interfaces/libpq/fe-connect.c</filename></para></listitem> - </itemizedlist> - - This is because of a namespace conflict between the standard - <filename>/usr/include/crypt.h</filename> header and the header - files provided by OpenSSL. - </para> - - <para> - Upgrading your OpenSSL installation to version 0.9.6a fixes this - problem. Solaris 9 and above has a newer version of OpenSSL. - </para> - </sect3> - - <sect3> <title>configure Complains About a Failed Test Program</title> <para> diff --git a/doc/src/sgml/jadetex.cfg b/doc/src/sgml/jadetex.cfg deleted file mode 100644 index 875598f151..0000000000 --- a/doc/src/sgml/jadetex.cfg +++ /dev/null @@ -1,89 +0,0 @@ -% doc/src/sgml/jadetex.cfg -% -% This file redefines \FlowObjectSetup and some related macros to greatly -% reduce the number of control sequence names created, and also to avoid -% creation of many useless hyperlink anchors (bookmarks) in PDF files. -% -% The original coding of \FlowObjectSetup defined a control sequence x@LABEL -% for pretty nearly every flow object in the file, whether that object was -% cross-referenced or not. Worse yet, it created a hyperlink anchor for -% every such object, which not only bloated the output PDF with useless -% anchors but consumed an additional control sequence name per anchor. -% This results in overrunning TeX's limited-size string pool. -% -% To fix, extend \PageLabel's already-existing mechanism whereby a p@LABEL -% control sequence is filled in only for labels that are referenced by at -% least one \Pageref call. We now also fill in p@LABEL for labels that are -% referenced by a \Link. Then, we can drop x@LABEL entirely, and use p@LABEL -% to control emission of both a hyperlink anchor and a page-number label. -% Now, both of those things are emitted for all and only the flow objects -% that have either a hyperlink reference or a page-number reference. -% We consume about one control sequence name per flow object plus one per -% referenced object, which is a lot better than three per flow object. -% -% (With a more invasive patch, we could track the need for an anchor and a -% page-number label separately, but that would probably require two control -% sequences for every flow object. Besides, many objects that have one kind -% of reference will have the other one too; that's certainly true for objects -% referenced in either the TOC or the index, for example.) -% -% -% In addition to checking p@LABEL not x@LABEL, this version of \FlowObjectSetup -% is fixed to clear \Label and \Element whether or not it emits an anchor -% and page label. Failure to do that seems to explain some pre-existing bugs -% in which certain SGML constructs weren't correctly cross-referenced. -% -\def\FlowObjectSetup#1{% -\ifDoFOBSet - \ifLabelElements - \ifx\Label\@empty\let\Label\Element\fi - \fi - \ifx\Label\@empty\else - \expandafter\ifx\csname p@\Label\endcsname\relax - \else - \bgroup - \ifNestedLink - \else - \hyper@anchorstart{\Label}\hyper@anchorend - \PageLabel{\Label}% - \fi - \egroup - \fi - \let\Label\@empty - \let\Element\@empty - \fi -\fi -} -% -% Adjust \PageLabel so that the p@NAME control sequence acquires a correct -% value immediately; this seems to be needed to avoid scenarios wherein -% additional TeX runs are needed to reach a stable state of the .aux file. -% -\def\PageLabel#1{% - \@bsphack - \expandafter\ifx\csname p@#1\endcsname\relax - \else - \protected@write\@auxout{}% - {\string\pagelabel{#1}{\thepage}}% - % Ensure the p@NAME control sequence acquires correct value immediately - \expandafter\xdef\csname p@#1\endcsname{\thepage}% - \fi - \@esphack} -% -% In \Link, add code to emit an aux-file entry if the p@NAME sequence isn't -% defined. Much as in \@Setref, this ensures we'll process the referenced -% item correctly on the next TeX run. -% -\def\Link#1{% - \begingroup - \SetupICs{#1}% - \ifx\Label\@empty\let\Label\Element\fi -% \typeout{Made a Link at \the\inputlineno, to \Label}% - \hyper@linkstart{\LinkType}{\Label}% - \NestedLinktrue - % If p@NAME control sequence isn't defined, emit dummy def to aux file - % so it will get defined properly on next run, much as in \@Setref - \expandafter\ifx\csname p@\Label\endcsname\relax - \immediate\write\@mainaux{\string\pagelabel{\Label}{qqq}}% - \fi -} diff --git a/doc/src/sgml/keywords.sgml b/doc/src/sgml/keywords.sgml index f3ecc1d187..7b1f8a149c 100644 --- a/doc/src/sgml/keywords.sgml +++ b/doc/src/sgml/keywords.sgml @@ -336,6 +336,13 @@ <entry></entry> </row> <row> + <entry><token>ATTACH</token></entry> + <entry>non-reserved</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> <entry><token>ATTRIBUTE</token></entry> <entry>non-reserved</entry> <entry>non-reserved</entry> @@ -1381,6 +1388,13 @@ <entry>reserved</entry> </row> <row> + <entry><token>DETACH</token></entry> + <entry>non-reserved</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> <entry><token>DETERMINISTIC</token></entry> <entry></entry> <entry>reserved</entry> @@ -2587,6 +2601,13 @@ <entry></entry> </row> <row> + <entry><token>LIST</token></entry> + <entry>non-reserved</entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> + <row> <entry><token>LISTEN</token></entry> <entry>non-reserved</entry> <entry></entry> diff --git a/doc/src/sgml/legal.sgml b/doc/src/sgml/legal.sgml index ae7f5a7d31..601d063a3a 100644 --- a/doc/src/sgml/legal.sgml +++ b/doc/src/sgml/legal.sgml @@ -1,9 +1,9 @@ <!-- doc/src/sgml/legal.sgml --> -<date>2016</date> +<date>2017</date> <copyright> - <year>1996-2016</year> + <year>1996-2017</year> <holder>The PostgreSQL Global Development Group</holder> </copyright> <copyright> @@ -27,7 +27,7 @@ <title>Legal Notice</title> <para> - <productname>PostgreSQL</productname> is Copyright © 1996-2016 + <productname>PostgreSQL</productname> is Copyright © 1996-2017 by the PostgreSQL Global Development Group. </para> diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index bf570e3fec..67647e1f35 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -410,6 +410,24 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); </para> </listitem> </varlistentry> + + <varlistentry id="libpq-connection-check-writable"> + <term><symbol>CONNECTION_CHECK_WRITABLE</symbol></term> + <listitem> + <para> + Checking if connection is able to handle write transactions. + </para> + </listitem> + </varlistentry> + + <varlistentry id="libpq-connection-consume"> + <term><symbol>CONNECTION_CONSUME</symbol></term> + <listitem> + <para> + Consuming any remaining response messages on connection. + </para> + </listitem> + </varlistentry> </variablelist> Note that, although these constants will remain (in order to maintain @@ -756,8 +774,10 @@ PGPing PQping(const char *conninfo); Several <application>libpq</> functions parse a user-specified string to obtain connection parameters. There are two accepted formats for these strings: plain <literal>keyword = value</literal> strings - and <ulink url="http://www.ietf.org/rfc/rfc3986.txt">RFC - 3986</ulink> URIs. + and URIs. URIs generally follow + <ulink url="http://www.ietf.org/rfc/rfc3986.txt">RFC + 3986</ulink>, except that multi-host connection strings are allowed + as further described below. </para> <sect3> @@ -792,7 +812,7 @@ host=localhost port=5432 dbname=mydb connect_timeout=10 <para> The general form for a connection <acronym>URI</acronym> is: <synopsis> -postgresql://[user[:password]@][netloc][:port][/dbname][?param1=value1&...] +postgresql://[user[:password]@][netloc][:port][,...][/dbname][?param1=value1&...] </synopsis> </para> @@ -809,6 +829,7 @@ postgresql://localhost/mydb postgresql://user@localhost postgresql://user:secret@localhost postgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapp +postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application_name=myapp </programlisting> Components of the hierarchical part of the <acronym>URI</acronym> can also be given as parameters. For example: @@ -856,6 +877,15 @@ postgresql:///dbname?host=/var/lib/postgresql postgresql://%2Fvar%2Flib%2Fpostgresql/dbname </programlisting> </para> + + <para> + It is possible to specify multiple host components, each with an optional + port component, in a single URI. A URI of the form + <literal>postgresql://host1:port1,host2:port2,host3:port3/</literal> + is equivalent to a connection string of the form + <literal>host=host1,host2,host3 port=port1,port2,port3</literal>. Each + host will be tried in turn until a connection is successfully established. + </para> </sect3> </sect2> @@ -870,12 +900,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <term><literal>host</literal></term> <listitem> <para> - Name of host to connect to.<indexterm><primary>host name</></> - If this begins with a slash, it specifies Unix-domain + Comma-separated list of host names.<indexterm><primary>host name</></> + If a host name begins with a slash, it specifies Unix-domain communication rather than TCP/IP communication; the value is the - name of the directory in which the socket file is stored. The - default behavior when <literal>host</literal> is not specified - is to connect to a Unix-domain + name of the directory in which the socket file is stored. If + multiple host names are specified, each will be tried in turn in + the order given. The default behavior when <literal>host</literal> is + not specified is to connect to a Unix-domain socket<indexterm><primary>Unix domain socket</></> in <filename>/tmp</filename> (or whatever socket directory was specified when <productname>PostgreSQL</> was built). On machines without @@ -930,7 +961,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname Note that authentication is likely to fail if <literal>host</> is not the name of the server at network address <literal>hostaddr</>. Also, note that <literal>host</> rather than <literal>hostaddr</> - is used to identify the connection in <filename>~/.pgpass</> (see + is used to identify the connection in a password file (see <xref linkend="libpq-pgpass">). </para> @@ -950,6 +981,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname Port number to connect to at the server host, or socket file name extension for Unix-domain connections.<indexterm><primary>port</></> + If the <literal>host</> parameter included multiple, comma-separated + hosts, this parameter may specify a list of ports of equal length, + or it may specify a single port number to be used for all hosts. </para> </listitem> </varlistentry> @@ -986,6 +1020,19 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname </listitem> </varlistentry> + <varlistentry id="libpq-connect-passfile" xreflabel="passfile"> + <term><literal>passfile</literal></term> + <listitem> + <para> + Specifies the name of the file used to store passwords + (see <xref linkend="libpq-pgpass">). + Defaults to <filename>~/.pgpass</filename>, or + <filename>%APPDATA%\postgresql\pgpass.conf</> on Microsoft Windows. + (No error is reported if this file does not exist.) + </para> + </listitem> + </varlistentry> + <varlistentry id="libpq-connect-connect-timeout" xreflabel="connect_timeout"> <term><literal>connect_timeout</literal></term> <listitem> @@ -993,6 +1040,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname Maximum wait for connection, in seconds (write as a decimal integer string). Zero or not specified means wait indefinitely. It is not recommended to use a timeout of less than 2 seconds. + This timeout applies separately to each connection attempt. + For example, if you specify two hosts and <literal>connect_timeout</> + is 5, each host will time out if no connection is made within 5 + seconds, so the total time spent waiting for a connection might be + up to 10 seconds. </para> </listitem> </varlistentry> @@ -1238,8 +1290,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <listitem> <para> If set to 1 (default), data sent over SSL connections will be - compressed (this requires <productname>OpenSSL</> version - 0.9.8 or later). + compressed. If set to 0, compression will be disabled (this requires <productname>OpenSSL</> 1.0.0 or later). This parameter is ignored if a connection without SSL is made, @@ -1367,6 +1418,23 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname </para> </listitem> </varlistentry> + + <varlistentry id="libpq-connect-target-session-attrs" xreflabel="target_session_attrs"> + <term><literal>target_session_attrs</literal></term> + <listitem> + <para> + If this parameter is set to <literal>read-write</literal>, only a + connection in which read-write transactions are accepted by default + is considered acceptable. The query + <literal>SHOW transaction_read_only</literal> will be sent upon any + successful connection; if it returns <literal>on</>, the connection + will be closed. If multiple hosts were specified in the connection + string, any remaining servers will be tried just as if the connection + attempt had failed. The default value of this parameter, + <literal>any</>, regards all connections as acceptable. + </para> + </listitem> + </varlistentry> </variablelist> </para> </sect2> @@ -1395,7 +1463,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <para> The following functions return parameter values established at connection. - These values are fixed for the life of the <structname>PGconn</> object. + These values are fixed for the life of the connection. If a multi-host + connection string is used, the values of <function>PQhost</>, + <function>PQport</>, and <function>PQpass</> can change if a new connection + is established using the same <structname>PGconn</> object. Other values + are fixed for the lifetime of the <structname>PGconn</> object. <variablelist> <varlistentry id="libpq-pqdb"> @@ -2767,6 +2839,22 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); </listitem> </varlistentry> + <varlistentry id="libpq-pg-diag-severity-nonlocalized"> + <term><symbol>PG_DIAG_SEVERITY_NONLOCALIZED</></term> + <listitem> + <para> + The severity; the field contents are <literal>ERROR</>, + <literal>FATAL</>, or <literal>PANIC</> (in an error message), + or <literal>WARNING</>, <literal>NOTICE</>, <literal>DEBUG</>, + <literal>INFO</>, or <literal>LOG</> (in a notice message). + This is identical to the <symbol>PG_DIAG_SEVERITY</> field except + that the contents are never localized. This is present only in + reports generated by <productname>PostgreSQL</> versions 9.6 + and later. + </para> + </listitem> + </varlistentry> + <varlistentry id="libpq-pg-diag-sqlstate"> <term> <symbol>PG_DIAG_SQLSTATE</> @@ -5794,11 +5882,11 @@ void PQconninfoFree(PQconninfoOption *connOptions); </listitem> </varlistentry> - <varlistentry id="libpq-pqencryptpassword"> + <varlistentry id="libpq-pqencryptpasswordconn"> <term> - <function>PQencryptPassword</function> + <function>PQencryptPasswordConn</function> <indexterm> - <primary>PQencryptPassword</primary> + <primary>PQencryptPasswordConn</primary> </indexterm> </term> @@ -5806,20 +5894,67 @@ void PQconninfoFree(PQconninfoOption *connOptions); <para> Prepares the encrypted form of a <productname>PostgreSQL</> password. <synopsis> -char * PQencryptPassword(const char *passwd, const char *user); +char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user, const char *algorithm); </synopsis> This function is intended to be used by client applications that wish to send commands like <literal>ALTER USER joe PASSWORD 'pwd'</>. It is good practice not to send the original cleartext password in such a command, because it might be exposed in command logs, activity displays, and so on. Instead, use this function to - convert the password to encrypted form before it is sent. The - arguments are the cleartext password, and the SQL name of the user - it is for. The return value is a string allocated by - <function>malloc</function>, or <symbol>NULL</symbol> if out of - memory. The caller can assume the string doesn't contain any - special characters that would require escaping. Use - <function>PQfreemem</> to free the result when done with it. + convert the password to encrypted form before it is sent. + </para> + + <para> + The <parameter>passwd</> and <parameter>user</> arguments + are the cleartext password, and the SQL name of the user it is for. + <parameter>algorithm</> specifies the encryption algorithm + to use to encrypt the password. Currently supported algorithms are + <literal>md5</> and <literal>scram-sha-256</> (<literal>on</> and + <literal>off</> are also accepted as aliases for <literal>md5</>, for + compatibility with older server versions). Note that support for + <literal>scram-sha-256</> was introduced in <productname>PostgreSQL</> + version 10, and will not work correctly with older server versions. If + <parameter>algorithm</> is <symbol>NULL</>, this function will query + the server for the current value of the + <xref linkend="guc-password-encryption"> setting. That can block, and + will fail if the current transaction is aborted, or if the connection + is busy executing another query. If you wish to use the default + algorithm for the server but want to avoid blocking, query + <varname>password_encryption</> yourself before calling + <function>PQencryptPasswordConn</>, and pass that value as the + <parameter>algorithm</>. + </para> + + <para> + The return value is a string allocated by <function>malloc</>. + The caller can assume the string doesn't contain any special characters + that would require escaping. Use <function>PQfreemem</> to free the + result when done with it. On error, returns <symbol>NULL</>, and + a suitable message is stored in the connection object. + </para> + + </listitem> + </varlistentry> + + <varlistentry id="libpq-pqencryptpassword"> + <term> + <function>PQencryptPassword</function> + <indexterm> + <primary>PQencryptPassword</primary> + </indexterm> + </term> + + <listitem> + <para> + Prepares the md5-encrypted form of a <productname>PostgreSQL</> password. + <synopsis> +char *PQencryptPassword(const char *passwd, const char *user); + </synopsis> + <function>PQencryptPassword</> is an older, deprecated version of + <function>PQencryptPasswodConn</>. The difference is that + <function>PQencryptPassword</> does not + require a connection object, and <literal>md5</> is always used as the + encryption algorithm. </para> </listitem> </varlistentry> @@ -6843,8 +6978,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) Use of this environment variable is not recommended for security reasons, as some operating systems allow non-root users to see process environment variables via - <application>ps</>; instead consider using the - <filename>~/.pgpass</> file (see <xref linkend="libpq-pgpass">). + <application>ps</>; instead consider using a password file + (see <xref linkend="libpq-pgpass">). </para> </listitem> @@ -6853,9 +6988,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) <indexterm> <primary><envar>PGPASSFILE</envar></primary> </indexterm> - <envar>PGPASSFILE</envar> specifies the name of the password file to - use for lookups. If not set, it defaults to <filename>~/.pgpass</> - (see <xref linkend="libpq-pgpass">). + <envar>PGPASSFILE</envar> behaves the same as the <xref + linkend="libpq-connect-passfile"> connection parameter. </para> </listitem> @@ -6884,22 +7018,6 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) <listitem> <para> <indexterm> - <primary><envar>PGREALM</envar></primary> - </indexterm> - <envar>PGREALM</envar> sets the Kerberos realm to use with - <productname>PostgreSQL</productname>, if it is different from the - local realm. If <envar>PGREALM</envar> is set, - <application>libpq</application> applications will attempt - authentication with servers for this realm and use separate ticket - files to avoid conflicts with local ticket files. This - environment variable is only used if GSSAPI authentication is - selected by the server. - </para> - </listitem> - - <listitem> - <para> - <indexterm> <primary><envar>PGOPTIONS</envar></primary> </indexterm> <envar>PGOPTIONS</envar> behaves the same as the <xref @@ -6934,6 +7052,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) </indexterm> <envar>PGREQUIRESSL</envar> behaves the same as the <xref linkend="libpq-connect-requiressl"> connection parameter. + This environment variable is deprecated in favor of the + <envar>PGSSLMODE</envar> variable; setting both variables suppresses the + effect of this one. </para> </listitem> @@ -7036,6 +7157,16 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) linkend="libpq-connect-client-encoding"> connection parameter. </para> </listitem> + + <listitem> + <para> + <indexterm> + <primary><envar>PGTARGETSESSIONATTRS</envar></primary> + </indexterm> + <envar>PGTARGETSESSIONATTRS</envar> behaves the same as the <xref + linkend="libpq-connect-target-session-attrs"> connection parameter. + </para> + </listitem> </itemizedlist> </para> @@ -7127,13 +7258,16 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) </indexterm> <para> - The file <filename>.pgpass</filename> in a user's home directory or the - file referenced by <envar>PGPASSFILE</envar> can contain passwords to + The file <filename>.pgpass</filename> in a user's home directory can + contain passwords to be used if the connection requires a password (and no password has been specified otherwise). On Microsoft Windows the file is named <filename>%APPDATA%\postgresql\pgpass.conf</> (where <filename>%APPDATA%</> refers to the Application Data subdirectory in the user's profile). + Alternatively, a password file can be specified + using the connection parameter <xref linkend="libpq-connect-passfile"> + or the environment variable <envar>PGPASSFILE</envar>. </para> <para> @@ -7159,8 +7293,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) </para> <para> - On Unix systems, the permissions on <filename>.pgpass</filename> must - disallow any access to world or group; achieve this by the command + On Unix systems, the permissions on a password file must + disallow any access to world or group; achieve this by a command such as <command>chmod 0600 ~/.pgpass</command>. If the permissions are less strict than this, the file will be ignored. On Microsoft Windows, it is assumed that the file is stored in a directory that is secure, so diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml index b69fa32f9d..23f5c96ddb 100644 --- a/doc/src/sgml/lobj.sgml +++ b/doc/src/sgml/lobj.sgml @@ -676,7 +676,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image * testlo.c * test using large objects with libpq * - * Portions Copyright (c) 1996-2016, PostgreSQL Global Development Group + * Portions Copyright (c) 1996-2017, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California * * diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml new file mode 100644 index 0000000000..36c157c43f --- /dev/null +++ b/doc/src/sgml/logical-replication.sgml @@ -0,0 +1,489 @@ +<!-- doc/src/sgml/logical-replication.sgml --> + +<chapter id="logical-replication"> + <title>Logical Replication</title> + + <para> + Logical replication is a method of replicating data objects and their + changes, based upon their replication identity (usually a primary key). We + use the term logical in contrast to physical replication, which uses exact + block addresses and byte-by-byte replication. PostgreSQL supports both + mechanisms concurrently, see <xref linkend="high-availability">. Logical + replication allows fine-grained control over both data replication and + security. + </para> + + <para> + Logical replication uses a <firstterm>publish</firstterm> + and <firstterm>subscribe</firstterm> model with one or + more <firstterm>subscribers</firstterm> subscribing to one or more + <firstterm>publications</firstterm> on a <firstterm>publisher</firstterm> + node. Subscribers pull data from the publications they subscribe to and may + subsequently re-publish data to allow cascading replication or more complex + configurations. + </para> + + <para> + Logical replication of a table typically starts with taking a snapshot + of the data on the publisher database and copying that to the subscriber. + Once that is done, the changes on the publisher are sent to the subscriber + as they occur in real-time. The subscriber applies the data in the same + order as the publisher so that transactional consistency is guaranteed for + publications within a single subscription. This method of data replication + is sometimes referred to as transactional replication. + </para> + + <para> + The typical use-cases for logical replication are: + + <itemizedlist> + <listitem> + <para> + Sending incremental changes in a single database or a subset of a + database to subscribers as they occur. + </para> + </listitem> + + <listitem> + <para> + Firing triggers for individual changes as they arrive on the + subscriber. + </para> + </listitem> + + <listitem> + <para> + Consolidating multiple databases into a single one (for example for + analytical purposes). + </para> + </listitem> + + <listitem> + <para> + Replicating between different major versions of PostgreSQL. + </para> + </listitem> + + <listitem> + <para> + Giving access to replicated data to different groups of users. + </para> + </listitem> + + <listitem> + <para> + Sharing a subset of the database between multiple databases. + </para> + </listitem> + </itemizedlist> + </para> + + <para> + The subscriber database behaves in the same way as any other PostgreSQL + instance and can be used as a publisher for other databases by defining its + own publications. When the subscriber is treated as read-only by + application, there will be no conflicts from a single subscription. On the + other hand, if there are other writes done either by an application or by other + subscribers to the same set of tables, conflicts can arise. + </para> + + <sect1 id="logical-replication-publication"> + <title>Publication</title> + + <para> + A <firstterm>publication</firstterm> can be defined on any physical + replication master. The node where a publication is defined is referred to + as <firstterm>publisher</firstterm>. A publication is a set of changes + generated from a table or a group of tables, and might also be described as + a change set or replication set. Each publication exists in only one database. + </para> + + <para> + Publications are different from schemas and do not affect how the table is + accessed. Each table can be added to multiple publications if needed. + Publications may currently only contain tables. Objects must be added + explicitly, except when a publication is created for <literal>ALL + TABLES</literal>. + </para> + + <para> + Publications can choose to limit the changes they produce to + any combination of <command>INSERT</command>, <command>UPDATE</command>, and + <command>DELETE</command>, similar to how triggers are fired by + particular event types. If a table without a <literal>REPLICA + IDENTITY</literal> is added to a publication that + replicates <command>UPDATE</command> or <command>DELETE</command> + operations then subsequent <command>UPDATE</command> + or <command>DELETE</command> operations will fail on the publisher. + </para> + + <para> + Every publication can have multiple subscribers. + </para> + + <para> + A publication is created using the <xref linkend="sql-createpublication"> + command and may later be altered or dropped using corresponding commands. + </para> + + <para> + The individual tables can be added and removed dynamically using + <xref linkend="sql-alterpublication">. Both the <literal>ADD + TABLE</literal> and <literal>DROP TABLE</literal> operations are + transactional; so the table will start or stop replicating at the correct + snapshot once the transaction has committed. + </para> + </sect1> + + <sect1 id="logical-replication-subscription"> + <title>Subscription</title> + + <para> + A <firstterm>subscription</firstterm> is the downstream side of logical + replication. The node where a subscription is defined is referred to as + the <firstterm>subscriber</firstterm>. A subscription defines the connection + to another database and set of publications (one or more) to which it wants + to subscribe. + </para> + + <para> + The subscriber database behaves in the same way as any other PostgreSQL + instance and can be used as a publisher for other databases by defining its + own publications. + </para> + + <para> + A subscriber node may have multiple subscriptions if desired. It is + possible to define multiple subscriptions between a single + publisher-subscriber pair, in which case care must be taken to ensure + that the subscribed publication objects don't overlap. + </para> + + <para> + Each subscription will receive changes via one replication slot (see + <xref linkend="streaming-replication-slots">). Additional temporary + replication slots may be required for the initial data synchronization + of pre-existing table data. + </para> + + <para> + Subscriptions are dumped by <command>pg_dump</command> if the current user + is a superuser. Otherwise a warning is written and subscriptions are + skipped, because non-superusers cannot read all subscription information + from the <structname>pg_subscription</structname> catalog. + </para> + + <para> + The subscription is added using <xref linkend="sql-createsubscription"> and + can be stopped/resumed at any time using the + <xref linkend="sql-altersubscription"> command and removed using + <xref linkend="sql-dropsubscription">. + </para> + + <para> + When a subscription is dropped and recreated, the synchronization + information is lost. This means that the data has to be resynchronized + afterwards. + </para> + + <para> + The schema definitions are not replicated, and the published tables must + exist on the subscriber. Only regular tables may be + the target of replication. For example, you can't replicate to a view. + </para> + + <para> + The tables are matched between the publisher and the subscriber using the + fully qualified table name. Replication to differently-named tables on the + subscriber is not supported. + </para> + + <para> + Columns of a table are also matched by name. A different order of columns + in the target table is allowed, but the column types have to match. The + target table can have additional columns not provided by the published + table. Those will be filled with their default values. + </para> + + <sect2 id="logical-replication-subscription-slot"> + <title>Replication Slot Management</title> + + <para> + As mentioned earlier, each (active) subscription receives changes from a + replication slot on the remote (publishing) side. Normally, the remote + replication slot is created automatically when the subscription is created + using <command>CREATE SUBSCRIPTION</command> and it is dropped + automatically when the subscription is dropped using <command>DROP + SUBSCRIPTION</command>. In some situations, however, it can be useful or + necessary to manipulate the subscription and the underlying replication + slot separately. Here are some scenarios: + + <itemizedlist> + <listitem> + <para> + When creating a subscription, the replication slot already exists. In + that case, the subscription can be created using + the <literal>create_slot = false</literal> option to associate with the + existing slot. + </para> + </listitem> + + <listitem> + <para> + When creating a subscription, the remote host is not reachable or in an + unclear state. In that case, the subscription can be created using + the <literal>connect = false</literal> option. The remote host will then not + be contacted at all. This is what <application>pg_dump</application> + uses. The remote replication slot will then have to be created + manually before the subscription can be activated. + </para> + </listitem> + + <listitem> + <para> + When dropping a subscription, the replication slot should be kept. + This could be useful when the subscriber database is being moved to a + different host and will be activated from there. In that case, + disassociate the slot from the subscription using <command>ALTER + SUBSCRIPTION</command> before attempting to drop the subscription. + </para> + </listitem> + + <listitem> + <para> + When dropping a subscription, the remote host is not reachable. In + that case, disassociate the slot from the subscription + using <command>ALTER SUBSCRIPTION</command> before attempting to drop + the subscription. If the remote database instance no longer exists, no + further action is then necessary. If, however, the remote database + instance is just unreachable, the replication slot should then be + dropped manually; otherwise it would continue to reserve WAL and might + eventually cause the disk to fill up. Such cases should be carefully + investigated. + </para> + </listitem> + </itemizedlist> + </para> + </sect2> + </sect1> + + <sect1 id="logical-replication-conflicts"> + <title>Conflicts</title> + + <para> + Logical replication behaves similarly to normal DML operations in that + the data will be updated even if it was changed locally on the subscriber + node. If incoming data violates any constraints the replication will + stop. This is referred to as a <firstterm>conflict</firstterm>. When + replicating <command>UPDATE</command> or <command>DELETE</command> + operations, missing data will not produce a conflict and such operations + will simply be skipped. + </para> + + <para> + A conflict will produce an error and will stop the replication; it must be + resolved manually by the user. Details about the conflict can be found in + the subscriber's server log. + </para> + + <para> + The resolution can be done either by changing data on the subscriber so + that it does not conflict with the incoming change or by skipping the + transaction that conflicts with the existing data. The transaction can be + skipped by calling the <link linkend="pg-replication-origin-advance"> + <function>pg_replication_origin_advance()</function></link> function with + a <parameter>node_name</parameter> corresponding to the subscription name, + and a position. The current position of origins can be seen in the + <link linkend="view-pg-replication-origin-status"> + <structname>pg_replication_origin_status</structname></link> system view. + </para> + </sect1> + + <sect1 id="logical-replication-architecture"> + <title>Architecture</title> + + <para> + Logical replication starts by copying a snapshot of the data on the + publisher database. Once that is done, changes on the publisher are sent + to the subscriber as they occur in real time. The subscriber applies data + in the order in which commits were made on the publisher so that + transactional consistency is guaranteed for the publications within any + single subscription. + </para> + + <para> + Logical replication is built with an architecture similar to physical + streaming replication (see <xref linkend="streaming-replication">). It is + implemented by <quote>walsender</quote> and <quote>apply</quote> + processes. The walsender process starts logical decoding (described + in <xref linkend="logicaldecoding">) of the WAL and loads the standard + logical decoding plugin (pgoutput). The plugin transforms the changes read + from WAL to the logical replication protocol + (see <xref linkend="protocol-logical-replication">) and filters the data + according to the publication specification. The data is then continuously + transferred using the streaming replication protocol to the apply worker, + which maps the data to local tables and applies the individual changes as + they are received, in correct transactional order. + </para> + + <para> + The apply process on the subscriber database always runs with + <varname>session_replication_role</varname> set + to <literal>replica</literal>, which produces the usual effects on triggers + and constraints. + </para> + + <sect2 id="logical-replication-snapshot"> + <title>Initial Snapshot</title> + <para> + The initial data in existing subscribed tables are snapshotted and + copied in a parallel instance of a special kind of apply process. + This process will create its own temporary replication slot and + copy the existing data. Once existing data is copied, the worker + enters synchronization mode, which ensures that the table is brought + up to a synchronized state with the main apply process by streaming + any changes that happened during the initial data copy using standard + logical replication. Once the synchronization is done, the control + of the replication of the table is given back to the main apply + process where the replication continues as normal. + </para> + </sect2> + </sect1> + + <sect1 id="logical-replication-monitoring"> + <title>Monitoring</title> + + <para> + Because logical replication is based on a similar architecture as + <link linkend="streaming-replication">physical streaming replication</link>, + the monitoring on a publication node is similar to monitoring of a + physical replication master + (see <xref linkend="streaming-replication-monitoring">). + </para> + + <para> + The monitoring information about subscription is visible in + <link linkend="pg-stat-subscription"><literal>pg_stat_subscription</literal></link>. + This view contains one row for every subscription worker. A subscription + can have zero or more active subscription workers depending on its state. + </para> + + <para> + Normally, there is a single apply process running for an enabled + subscription. A disabled subscription or a crashed subscription will have + zero rows in this view. If the initial data synchronization of any + table is in progress, there will be additional workers for the tables + being synchronized. + </para> + </sect1> + + <sect1 id="logical-replication-security"> + <title>Security</title> + + <para> + The role used for the replication connection must have + the <literal>REPLICATION</literal> attribute. Access for the role must be + configured in <filename>pg_hba.conf</filename>. + </para> + + <para> + To create a publication, the user must have the <literal>CREATE</literal> + privilege in the database. + </para> + + <para> + To add tables to a publication, the user must have ownership rights on the + table. To create a publication that publishes all tables automatically, + the user must be a superuser. + </para> + + <para> + To create a subscription, the user must be a superuser. + </para> + + <para> + The subscription apply process will run in the local database with the + privileges of a superuser. + </para> + + <para> + Privileges are only checked once at the start of a replication connection. + They are not re-checked as each change record is read from the publisher, + nor are they re-checked for each change when applied. + </para> + </sect1> + + <sect1 id="logical-replication-config"> + <title>Configuration Settings</title> + + <para> + Logical replication requires several configuration options to be set. + </para> + + <para> + On the publisher side, <varname>wal_level</varname> must be set to + <literal>logical</literal>, and <varname>max_replication_slots</varname> + must be set to at least the number of subscriptions expected to connect, + plus some reserve for table synchronization. And + <varname>max_wal_senders</varname> should be set to at least the same as + <varname>max_replication_slots</varname> plus the number of physical + replicas that are connected at the same time. + </para> + + <para> + The subscriber also requires the <varname>max_replication_slots</varname> + to be set. In this case it should be set to at least the number of + subscriptions that will be added to the subscriber. + <varname>max_logical_replication_workers</varname> must be set to at + least the number of subscriptions, again plus some reserve for the table + synchronization. Additionally the <varname>max_worker_processes</varname> + may need to be adjusted to accommodate for replication workers, at least + (<varname>max_logical_replication_workers</varname> + + <literal>1</literal>). Note that some extensions and parallel queries + also take worker slots from <varname>max_worker_processes</varname>. + </para> + </sect1> + + <sect1 id="logical-replication-quick-setup"> + <title>Quick Setup</title> + + <para> + First set the configuration options in <filename>postgresql.conf</filename>: +<programlisting> +wal_level = logical +</programlisting> + The other required settings have default values that are sufficient for a + basic setup. + </para> + + <para> + <filename>pg_hba.conf</filename> needs to be adjusted to allow replication + (the values here depend on your actual network configuration and user you + want to use for connecting): +<programlisting> +host all repuser 0.0.0.0/0 md5 +</programlisting> + </para> + + <para> + Then on the publisher database: +<programlisting> +CREATE PUBLICATION mypub FOR TABLE users, departments; +</programlisting> + </para> + + <para> + And on the subscriber database: +<programlisting> +CREATE SUBSCRIPTION mysub CONNECTION 'dbname=foo host=bar user=repuser' PUBLICATION mypub; +</programlisting> + </para> + + <para> + The above will start the replication process, which synchronizes the + initial table contents of the tables <literal>users</literal> and + <literal>departments</literal> and then starts replicating + incremental changes to those tables. + </para> + </sect1> +</chapter> diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml index c42082002e..8dcfc6c742 100644 --- a/doc/src/sgml/logicaldecoding.sgml +++ b/doc/src/sgml/logicaldecoding.sgml @@ -12,7 +12,6 @@ <para> Changes are sent out in streams identified by logical replication slots. - Each stream outputs each change exactly once. </para> <para> @@ -57,8 +56,8 @@ <programlisting> postgres=# -- Create a slot named 'regression_slot' using the output plugin 'test_decoding' postgres=# SELECT * FROM pg_create_logical_replication_slot('regression_slot', 'test_decoding'); - slot_name | xlog_position ------------------+--------------- + slot_name | lsn +-----------------+----------- regression_slot | 0/16B1970 (1 row) @@ -70,8 +69,8 @@ postgres=# SELECT slot_name, plugin, slot_type, database, active, restart_lsn, c postgres=# -- There are no changes to see yet postgres=# SELECT * FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL); - location | xid | data -----------+-----+------ + lsn | xid | data +-----+-----+------ (0 rows) postgres=# CREATE TABLE data(id serial primary key, data text); @@ -79,17 +78,17 @@ CREATE TABLE postgres=# -- DDL isn't replicated, so all you'll see is the transaction postgres=# SELECT * FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL); - location | xid | data ------------+-----+------------ - 0/16D5D48 | 688 | BEGIN 688 - 0/16E0380 | 688 | COMMIT 688 + lsn | xid | data +-----------+-------+-------------- + 0/BA2DA58 | 10297 | BEGIN 10297 + 0/BA5A5A0 | 10297 | COMMIT 10297 (2 rows) postgres=# -- Once changes are read, they're consumed and not emitted postgres=# -- in a subsequent call: postgres=# SELECT * FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL); - location | xid | data -----------+-----+------ + lsn | xid | data +-----+-----+------ (0 rows) postgres=# BEGIN; @@ -98,41 +97,41 @@ postgres=# INSERT INTO data(data) VALUES('2'); postgres=# COMMIT; postgres=# SELECT * FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL); - location | xid | data ------------+-----+----------------------------------------------- - 0/16E0478 | 689 | BEGIN 689 - 0/16E0478 | 689 | table public.data: INSERT: id[integer]:1 data[text]:'1' - 0/16E0580 | 689 | table public.data: INSERT: id[integer]:2 data[text]:'2' - 0/16E0650 | 689 | COMMIT 689 + lsn | xid | data +-----------+-------+--------------------------------------------------------- + 0/BA5A688 | 10298 | BEGIN 10298 + 0/BA5A6F0 | 10298 | table public.data: INSERT: id[integer]:1 data[text]:'1' + 0/BA5A7F8 | 10298 | table public.data: INSERT: id[integer]:2 data[text]:'2' + 0/BA5A8A8 | 10298 | COMMIT 10298 (4 rows) postgres=# INSERT INTO data(data) VALUES('3'); postgres=# -- You can also peek ahead in the change stream without consuming changes postgres=# SELECT * FROM pg_logical_slot_peek_changes('regression_slot', NULL, NULL); - location | xid | data ------------+-----+----------------------------------------------- - 0/16E09C0 | 690 | BEGIN 690 - 0/16E09C0 | 690 | table public.data: INSERT: id[integer]:3 data[text]:'3' - 0/16E0B90 | 690 | COMMIT 690 + lsn | xid | data +-----------+-------+--------------------------------------------------------- + 0/BA5A8E0 | 10299 | BEGIN 10299 + 0/BA5A8E0 | 10299 | table public.data: INSERT: id[integer]:3 data[text]:'3' + 0/BA5A990 | 10299 | COMMIT 10299 (3 rows) postgres=# -- The next call to pg_logical_slot_peek_changes() returns the same changes again postgres=# SELECT * FROM pg_logical_slot_peek_changes('regression_slot', NULL, NULL); - location | xid | data ------------+-----+----------------------------------------------- - 0/16E09C0 | 690 | BEGIN 690 - 0/16E09C0 | 690 | table public.data: INSERT: id[integer]:3 data[text]:'3' - 0/16E0B90 | 690 | COMMIT 690 + lsn | xid | data +-----------+-------+--------------------------------------------------------- + 0/BA5A8E0 | 10299 | BEGIN 10299 + 0/BA5A8E0 | 10299 | table public.data: INSERT: id[integer]:3 data[text]:'3' + 0/BA5A990 | 10299 | COMMIT 10299 (3 rows) postgres=# -- options can be passed to output plugin, to influence the formatting postgres=# SELECT * FROM pg_logical_slot_peek_changes('regression_slot', NULL, NULL, 'include-timestamp', 'on'); - location | xid | data ------------+-----+----------------------------------------------- - 0/16E09C0 | 690 | BEGIN 690 - 0/16E09C0 | 690 | table public.data: INSERT: id[integer]:3 data[text]:'3' - 0/16E0B90 | 690 | COMMIT 690 (at 2014-02-27 16:41:51.863092+01) + lsn | xid | data +-----------+-------+--------------------------------------------------------- + 0/BA5A8E0 | 10299 | BEGIN 10299 + 0/BA5A8E0 | 10299 | table public.data: INSERT: id[integer]:3 data[text]:'3' + 0/BA5A990 | 10299 | COMMIT 10299 (at 2017-05-10 12:07:21.272494-04) (3 rows) postgres=# -- Remember to destroy a slot you no longer need to stop it consuming @@ -204,8 +203,7 @@ $ pg_recvlogical -d postgres --slot test --drop-slot In the context of logical replication, a slot represents a stream of changes that can be replayed to a client in the order they were made on the origin server. Each slot streams a sequence of changes from a single - database, sending each change exactly once (except when peeking forward - in the stream). + database. </para> <note> @@ -222,6 +220,20 @@ $ pg_recvlogical -d postgres --slot test --drop-slot </para> <para> + A logical slot will emit each change just once in normal operation. + The current position of each slot is persisted only at checkpoint, so in + the case of a crash the slot may return to an earlier LSN, which will + then cause recent changes to be resent when the server restarts. + Logical decoding clients are responsible for avoiding ill effects from + handling the same message more than once. Clients may wish to record + the last LSN they saw when decoding and skip over any repeated data or + (when using the replication protocol) request that decoding start from + that LSN rather than letting the server determine the start point. + The Replication Progress Tracking feature is designed for this purpose, + refer to <link linkend="replication-origins">replication origins</link>. + </para> + + <para> Multiple independent slots may exist for a single database. Each slot has its own state, allowing different consumers to receive changes from different points in the database change stream. For most applications, a @@ -259,8 +271,9 @@ $ pg_recvlogical -d postgres --slot test --drop-slot <sect2> <title>Exported Snapshots</title> <para> - When a new replication slot is created using the streaming replication interface, - a snapshot is exported + When a new replication slot is created using the streaming replication + interface (see <xref linkend="protocol-replication-create-slot">), a + snapshot is exported (see <xref linkend="functions-snapshot-synchronization">), which will show exactly the state of the database after which all changes will be included in the change stream. This can be used to create a new replica by @@ -270,6 +283,12 @@ $ pg_recvlogical -d postgres --slot test --drop-slot database's state at that point in time, which afterwards can be updated using the slot's contents without losing any changes. </para> + <para> + Creation of a snapshot is not always possible. In particular, it will + fail when connected to a hot standby. Applications that do not require + snapshot export may suppress it with the <literal>NOEXPORT_SNAPSHOT</> + option. + </para> </sect2> </sect1> @@ -368,7 +387,7 @@ typedef struct OutputPluginCallbacks LogicalDecodeShutdownCB shutdown_cb; } OutputPluginCallbacks; -typedef void (*LogicalOutputPluginInit)(struct OutputPluginCallbacks *cb); +typedef void (*LogicalOutputPluginInit) (struct OutputPluginCallbacks *cb); </programlisting> The <function>begin_cb</function>, <function>change_cb</function> and <function>commit_cb</function> callbacks are required, @@ -407,7 +426,7 @@ CREATE TABLE another_catalog_table(data text) WITH (user_catalog_table = true); data in a data type that can contain arbitrary data (e.g., <type>bytea</type>) is cumbersome. If the output plugin only outputs textual data in the server's encoding, it can declare that by - setting <literal>OutputPluginOptions.output_mode</> + setting <literal>OutputPluginOptions.output_type</> to <literal>OUTPUT_PLUGIN_TEXTUAL_OUTPUT</> instead of <literal>OUTPUT_PLUGIN_BINARY_OUTPUT</> in the <link linkend="logicaldecoding-output-plugin-startup">startup @@ -453,11 +472,9 @@ CREATE TABLE another_catalog_table(data text) WITH (user_catalog_table = true); a replication slot is created or asked to stream changes, independent of the number of changes that are ready to be put out. <programlisting> -typedef void (*LogicalDecodeStartupCB) ( - struct LogicalDecodingContext *ctx, - OutputPluginOptions *options, - bool is_init -); +typedef void (*LogicalDecodeStartupCB) (struct LogicalDecodingContext *ctx, + OutputPluginOptions *options, + bool is_init); </programlisting> The <literal>is_init</literal> parameter will be true when the replication slot is being created and false @@ -492,9 +509,7 @@ typedef struct OutputPluginOptions be used to deallocate resources private to the output plugin. The slot isn't necessarily being dropped, streaming is just being stopped. <programlisting> -typedef void (*LogicalDecodeShutdownCB) ( - struct LogicalDecodingContext *ctx -); +typedef void (*LogicalDecodeShutdownCB) (struct LogicalDecodingContext *ctx); </programlisting> </para> </sect3> @@ -507,10 +522,8 @@ typedef void (*LogicalDecodeShutdownCB) ( start of a committed transaction has been decoded. Aborted transactions and their contents never get decoded. <programlisting> -typedef void (*LogicalDecodeBeginCB) ( - struct LogicalDecodingContext *, - ReorderBufferTXN *txn -); +typedef void (*LogicalDecodeBeginCB) (struct LogicalDecodingContext *ctx, + ReorderBufferTXN *txn); </programlisting> The <parameter>txn</parameter> parameter contains meta information about the transaction, like the time stamp at which it has been committed and @@ -528,10 +541,9 @@ typedef void (*LogicalDecodeBeginCB) ( rows will have been called before this, if there have been any modified rows. <programlisting> -typedef void (*LogicalDecodeCommitCB) ( - struct LogicalDecodingContext *, - ReorderBufferTXN *txn -); +typedef void (*LogicalDecodeCommitCB) (struct LogicalDecodingContext *ctx, + ReorderBufferTXN *txn, + XLogRecPtr commit_lsn); </programlisting> </para> </sect3> @@ -547,12 +559,10 @@ typedef void (*LogicalDecodeCommitCB) ( several rows at once the callback will be called individually for each row. <programlisting> -typedef void (*LogicalDecodeChangeCB) ( - struct LogicalDecodingContext *ctx, - ReorderBufferTXN *txn, - Relation relation, - ReorderBufferChange *change -); +typedef void (*LogicalDecodeChangeCB) (struct LogicalDecodingContext *ctx, + ReorderBufferTXN *txn, + Relation relation, + ReorderBufferChange *change); </programlisting> The <parameter>ctx</parameter> and <parameter>txn</parameter> parameters have the same contents as for the <function>begin_cb</function> @@ -582,10 +592,8 @@ typedef void (*LogicalDecodeChangeCB) ( from <parameter>origin_id</parameter> is of interest to the output plugin. <programlisting> -typedef bool (*LogicalDecodeFilterByOriginCB) ( - struct LogicalDecodingContext *ctx, - RepNodeId origin_id -); +typedef bool (*LogicalDecodeFilterByOriginCB) (struct LogicalDecodingContext *ctx, + RepOriginId origin_id); </programlisting> The <parameter>ctx</parameter> parameter has the same contents as for the other callbacks. No information but the origin is @@ -611,22 +619,20 @@ typedef bool (*LogicalDecodeFilterByOriginCB) ( The optional <function>message_cb</function> callback is called whenever a logical decoding message has been decoded. <programlisting> -typedef void (*LogicalDecodeMessageCB) ( - struct LogicalDecodingContext *, - ReorderBufferTXN *txn, - XLogRecPtr message_lsn, - bool transactional, - const char *prefix, - Size message_size, - const char *message -); +typedef void (*LogicalDecodeMessageCB) (struct LogicalDecodingContext *ctx, + ReorderBufferTXN *txn, + XLogRecPtr message_lsn, + bool transactional, + const char *prefix, + Size message_size, + const char *message); </programlisting> The <parameter>txn</parameter> parameter contains meta information about the transaction, like the time stamp at which it has been committed and its XID. Note however that it can be NULL when the message is non-transactional and the XID was not assigned yet in the transaction which logged the message. The <parameter>lsn</parameter> has WAL - position of the message. The <parameter>transactional</parameter> says + location of the message. The <parameter>transactional</parameter> says if the message was sent as transactional or not. The <parameter>prefix</parameter> is arbitrary null-terminated prefix which can be used for identifying interesting messages for the current diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml index fbab22e715..cfaa0da4b8 100644 --- a/doc/src/sgml/maintenance.sgml +++ b/doc/src/sgml/maintenance.sgml @@ -419,7 +419,8 @@ </para> <para> - <productname>PostgreSQL</productname>'s MVCC transaction semantics + <productname>PostgreSQL</productname>'s + <link linkend="mvcc-intro">MVCC</link> transaction semantics depend on being able to compare transaction ID (<acronym>XID</>) numbers: a row version with an insertion XID greater than the current transaction's XID is <quote>in the future</> and should not be visible @@ -443,13 +444,10 @@ <para> The reason that periodic vacuuming solves the problem is that <command>VACUUM</> will mark rows as <emphasis>frozen</>, indicating that - they were inserted by a transaction which committed sufficiently far in - the past that the effects of the inserting transaction is certain to be - visible, from an MVCC perspective, to all current and future transactions. - <productname>PostgreSQL</> reserves a special XID, - <literal>FrozenTransactionId</>, which does not follow the normal XID - comparison rules and is always considered older - than every normal XID. Normal XIDs are + they were inserted by a transaction that committed sufficiently far in + the past that the effects of the inserting transaction are certain to be + visible to all current and future transactions. + Normal XIDs are compared using modulo-2<superscript>32</> arithmetic. This means that for every normal XID, there are two billion XIDs that are <quote>older</> and two billion that are <quote>newer</>; another @@ -459,16 +457,40 @@ the next two billion transactions, no matter which normal XID we are talking about. If the row version still exists after more than two billion transactions, it will suddenly appear to be in the future. To - prevent this, frozen row versions are treated as if the inserting XID were + prevent this, <productname>PostgreSQL</> reserves a special XID, + <literal>FrozenTransactionId</>, which does not follow the normal XID + comparison rules and is always considered older + than every normal XID. + Frozen row versions are treated as if the inserting XID were <literal>FrozenTransactionId</>, so that they will appear to be <quote>in the past</> to all normal transactions regardless of wraparound issues, and so such row versions will be valid until deleted, no matter how long that is. </para> + <note> + <para> + In <productname>PostgreSQL</> versions before 9.4, freezing was + implemented by actually replacing a row's insertion XID + with <literal>FrozenTransactionId</>, which was visible in the + row's <structname>xmin</> system column. Newer versions just set a flag + bit, preserving the row's original <structname>xmin</> for possible + forensic use. However, rows with <structname>xmin</> equal + to <literal>FrozenTransactionId</> (2) may still be found + in databases <application>pg_upgrade</>'d from pre-9.4 versions. + </para> + <para> + Also, system catalogs may contain rows with <structname>xmin</> equal + to <literal>BootstrapTransactionId</> (1), indicating that they were + inserted during the first phase of <application>initdb</>. + Like <literal>FrozenTransactionId</>, this special XID is treated as + older than every normal XID. + </para> + </note> + <para> <xref linkend="guc-vacuum-freeze-min-age"> - controls how old an XID value has to be before its row version will be + controls how old an XID value has to be before rows bearing that XID will be frozen. Increasing this setting may avoid unnecessary work if the rows that would otherwise be frozen will soon be modified again, but decreasing this setting increases @@ -478,10 +500,10 @@ <para> <command>VACUUM</> uses the <link linkend="storage-vm">visibility map</> - to determine which pages of a relation must be scanned. Normally, it - will skips pages that don't have any dead row versions even if those pages + to determine which pages of a table must be scanned. Normally, it + will skip pages that don't have any dead row versions even if those pages might still have row versions with old XID values. Therefore, normal - scans won't succeed in freezing every row version in the table. + <command>VACUUM</>s won't always freeze every old row version in the table. Periodically, <command>VACUUM</> will perform an <firstterm>aggressive vacuum</>, skipping only those pages which contain neither dead rows nor any unfrozen XID or MXID values. @@ -541,18 +563,18 @@ <para> The sole disadvantage of increasing <varname>autovacuum_freeze_max_age</> (and <varname>vacuum_freeze_table_age</> along with it) - is that the <filename>pg_clog</> subdirectory of the database cluster + is that the <filename>pg_xact</> subdirectory of the database cluster will take more space, because it must store the commit status of all transactions back to the <varname>autovacuum_freeze_max_age</> horizon. The commit status uses two bits per transaction, so if <varname>autovacuum_freeze_max_age</> is set to its maximum allowed - value of two billion, <filename>pg_clog</> can be expected to + value of two billion, <filename>pg_xact</> can be expected to grow to about half a gigabyte. If this is trivial compared to your total database size, setting <varname>autovacuum_freeze_max_age</> to its maximum allowed value is recommended. Otherwise, set it depending - on what you are willing to allow for <filename>pg_clog</> storage. + on what you are willing to allow for <filename>pg_xact</> storage. (The default, 200 million transactions, translates to about 50MB of - <filename>pg_clog</> storage.) + <filename>pg_xact</> storage.) </para> <para> diff --git a/doc/src/sgml/mk_feature_tables.pl b/doc/src/sgml/mk_feature_tables.pl index 45dea798cd..9b111b8b40 100644 --- a/doc/src/sgml/mk_feature_tables.pl +++ b/doc/src/sgml/mk_feature_tables.pl @@ -2,13 +2,15 @@ # doc/src/sgml/mk_feature_tables.pl +use strict; + my $yesno = $ARGV[0]; -open PACK, $ARGV[1] or die; +open my $pack, '<', $ARGV[1] or die; my %feature_packages; -while (<PACK>) +while (<$pack>) { chomp; my ($fid, $pname) = split /\t/; @@ -22,13 +24,13 @@ while (<PACK>) } } -close PACK; +close $pack; -open FEAT, $ARGV[2] or die; +open my $feat, '<', $ARGV[2] or die; print "<tbody>\n"; -while (<FEAT>) +while (<$feat>) { chomp; my ($feature_id, $feature_name, $subfeature_id, @@ -67,4 +69,4 @@ while (<FEAT>) print "</tbody>\n"; -close FEAT; +close $feat; diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 077642878e..79ca45a156 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -309,6 +309,14 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser </row> <row> + <entry><structname>pg_stat_subscription</><indexterm><primary>pg_stat_subscription</primary></indexterm></entry> + <entry>At least one row per subscription, showing information about + the subscription workers. + See <xref linkend="pg-stat-subscription"> for details. + </entry> + </row> + + <row> <entry><structname>pg_stat_ssl</><indexterm><primary>pg_stat_ssl</primary></indexterm></entry> <entry>One row per connection (regular and replication), showing information about SSL used on this connection. @@ -316,6 +324,14 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser </entry> </row> + <row> + <entry><structname>pg_stat_progress_vacuum</><indexterm><primary>pg_stat_progress_vacuum</primary></indexterm></entry> + <entry>One row for each backend (including autovacuum worker processes) running + <command>VACUUM</>, showing current progress. + See <xref linkend='vacuum-progress-reporting'>. + </entry> + </row> + </tbody> </tgroup> </table> @@ -507,12 +523,6 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser yet included in <structname>pg_stat_user_functions</>).</entry> </row> - <row> - <entry><structname>pg_stat_progress_vacuum</><indexterm><primary>pg_stat_progress_vacuum</primary></indexterm></entry> - <entry>One row for each backend (including autovacuum worker processes) running - <command>VACUUM</>, showing current progress. - See <xref linkend='vacuum-progress-reporting'>.</entry> - </row> </tbody> </tgroup> </table> @@ -612,8 +622,8 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser <row> <entry><structfield>backend_start</></entry> <entry><type>timestamp with time zone</></entry> - <entry>Time when this process was started, i.e., when the - client connected to the server + <entry>Time when this process was started. For client backends, + this is the time the client connected to the server. </entry> </row> <row> @@ -646,18 +656,11 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser <itemizedlist> <listitem> <para> - <literal>LWLockNamed</>: The backend is waiting for a specific named - lightweight lock. Each such lock protects a particular data - structure in shared memory. <literal>wait_event</> will contain - the name of the lightweight lock. - </para> - </listitem> - <listitem> - <para> - <literal>LWLockTranche</>: The backend is waiting for one of a - group of related lightweight locks. All locks in the group perform - a similar function; <literal>wait_event</> will identify the general - purpose of locks in that group. + <literal>LWLock</>: The backend is waiting for a lightweight lock. + Each such lock protects a particular data structure in shared memory. + <literal>wait_event</> will contain a name identifying the purpose + of the lightweight lock. (Some locks have specific names; others + are part of a group of locks each with a similar purpose.) </para> </listitem> <listitem> @@ -679,6 +682,48 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser buffer in question. </para> </listitem> + <listitem> + <para> + <literal>Activity</>: The server process is idle. This is used by + system processes waiting for activity in their main processing loop. + <literal>wait_event</> will identify the specific wait point. + </para> + </listitem> + <listitem> + <para> + <literal>Extension</>: The server process is waiting for activity + in an extension module. This category is useful for modules to + track custom waiting points. + </para> + </listitem> + <listitem> + <para> + <literal>Client</>: The server process is waiting for some activity + on a socket from user applications, and that the server expects + something to happen that is independent from its internal processes. + <literal>wait_event</> will identify the specific wait point. + </para> + </listitem> + <listitem> + <para> + <literal>IPC</>: The server process is waiting for some activity + from another process in the server. <literal>wait_event</> will + identify the specific wait point. + </para> + </listitem> + <listitem> + <para> + <literal>Timeout</>: The server process is waiting for a timeout + to expire. <literal>wait_event</> will identify the specific wait + point. + </para> + </listitem> + <listitem> + <para> + <literal>IO</>: The server process is waiting for a IO to complete. + <literal>wait_event</> will identify the specific wait point. + </para> + </listitem> </itemizedlist> </entry> </row> @@ -749,7 +794,20 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser <entry>Text of this backend's most recent query. If <structfield>state</> is <literal>active</> this field shows the currently executing query. In all other states, it shows the last query - that was executed. + that was executed. By default the query text is truncated at 1024 + characters; this value can be changed via the parameter + <xref linkend="guc-track-activity-query-size">. + </entry> + </row> + <row> + <entry><structfield>backend_type</structfield></entry> + <entry><type>text</type></entry> + <entry>Type of current backend. Possible types are + <literal>autovacuum launcher</>, <literal>autovacuum worker</>, + <literal>background worker</>, <literal>background writer</>, + <literal>client backend</>, <literal>checkpointer</>, + <literal>startup</>, <literal>walreceiver</>, + <literal>walsender</> and <literal>walwriter</>. </entry> </row> </tbody> @@ -787,7 +845,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser <tbody> <row> - <entry morerows="41"><literal>LWLockNamed</></entry> + <entry morerows="59"><literal>LWLock</></entry> <entry><literal>ShmemIndexLock</></entry> <entry>Waiting to find or allocate space in shared memory.</entry> </row> @@ -973,7 +1031,10 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser <entry>Waiting to read or update old snapshot control information.</entry> </row> <row> - <entry morerows="15"><literal>LWLockTranche</></entry> + <entry><literal>CLogTruncationLock</></entry> + <entry>Waiting to truncate the write-ahead log or waiting for write-ahead log truncation to finish.</entry> + </row> + <row> <entry><literal>clog</></entry> <entry>Waiting for I/O on a clog (transaction status) buffer.</entry> </row> @@ -1040,6 +1101,14 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser <entry>Waiting to add or examine predicate lock information.</entry> </row> <row> + <entry><literal>parallel_query_dsa</></entry> + <entry>Waiting for parallel query dynamic shared memory allocation lock.</entry> + </row> + <row> + <entry><literal>tbm</></entry> + <entry>Waiting for TBM shared iterator lock.</entry> + </row> + <row> <entry morerows="9"><literal>Lock</></entry> <entry><literal>relation</></entry> <entry>Waiting to acquire a lock on a relation.</entry> @@ -1085,6 +1154,416 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser <entry><literal>BufferPin</></entry> <entry>Waiting to acquire a pin on a buffer.</entry> </row> + <row> + <entry morerows="11"><literal>Activity</></entry> + <entry><literal>ArchiverMain</></entry> + <entry>Waiting in main loop of the archiver process.</entry> + </row> + <row> + <entry><literal>AutoVacuumMain</></entry> + <entry>Waiting in main loop of autovacuum launcher process.</entry> + </row> + <row> + <entry><literal>BgWriterHibernate</></entry> + <entry>Waiting in background writer process, hibernating.</entry> + </row> + <row> + <entry><literal>BgWriterMain</></entry> + <entry>Waiting in main loop of background writer process background worker.</entry> + </row> + <row> + <entry><literal>CheckpointerMain</></entry> + <entry>Waiting in main loop of checkpointer process.</entry> + </row> + <row> + <entry><literal>PgStatMain</></entry> + <entry>Waiting in main loop of the statistics collector process.</entry> + </row> + <row> + <entry><literal>RecoveryWalAll</></entry> + <entry>Waiting for WAL from any kind of source (local, archive or stream) at recovery.</entry> + </row> + <row> + <entry><literal>RecoveryWalStream</></entry> + <entry>Waiting for WAL from a stream at recovery.</entry> + </row> + <row> + <entry><literal>SysLoggerMain</></entry> + <entry>Waiting in main loop of syslogger process.</entry> + </row> + <row> + <entry><literal>WalReceiverMain</></entry> + <entry>Waiting in main loop of WAL receiver process.</entry> + </row> + <row> + <entry><literal>WalSenderMain</></entry> + <entry>Waiting in main loop of WAL sender process.</entry> + </row> + <row> + <entry><literal>WalWriterMain</></entry> + <entry>Waiting in main loop of WAL writer process.</entry> + </row> + <row> + <entry morerows="5"><literal>Client</></entry> + <entry><literal>ClientRead</></entry> + <entry>Waiting to read data from the client.</entry> + </row> + <row> + <entry><literal>ClientWrite</></entry> + <entry>Waiting to write data from the client.</entry> + </row> + <row> + <entry><literal>SSLOpenServer</></entry> + <entry>Waiting for SSL while attempting connection.</entry> + </row> + <row> + <entry><literal>WalReceiverWaitStart</></entry> + <entry>Waiting for startup process to send initial data for streaming replication.</entry> + </row> + <row> + <entry><literal>WalSenderWaitForWAL</></entry> + <entry>Waiting for WAL to be flushed in WAL sender process.</entry> + </row> + <row> + <entry><literal>WalSenderWriteData</></entry> + <entry>Waiting for any activity when processing replies from WAL receiver in WAL sender process.</entry> + </row> + <row> + <entry><literal>Extension</></entry> + <entry><literal>Extension</></entry> + <entry>Waiting in an extension.</entry> + </row> + <row> + <entry morerows="12"><literal>IPC</></entry> + <entry><literal>BgWorkerShutdown</></entry> + <entry>Waiting for background worker to shut down.</entry> + </row> + <row> + <entry><literal>BgWorkerStartup</></entry> + <entry>Waiting for background worker to start up.</entry> + </row> + <row> + <entry><literal>BtreePage</></entry> + <entry>Waiting for the page number needed to continue a parallel btree scan to become available.</entry> + </row> + <row> + <entry><literal>ExecuteGather</></entry> + <entry>Waiting for activity from child process when executing <literal>Gather</> node.</entry> + </row> + <row> + <entry><literal>MessageQueueInternal</></entry> + <entry>Waiting for other process to be attached in shared message queue.</entry> + </row> + <row> + <entry><literal>MessageQueuePutMessage</></entry> + <entry>Waiting to write a protocol message to a shared message queue.</entry> + </row> + <row> + <entry><literal>MessageQueueReceive</></entry> + <entry>Waiting to receive bytes from a shared message queue.</entry> + </row> + <row> + <entry><literal>MessageQueueSend</></entry> + <entry>Waiting to send bytes to a shared message queue.</entry> + </row> + <row> + <entry><literal>ParallelFinish</></entry> + <entry>Waiting for parallel workers to finish computing.</entry> + </row> + <row> + <entry><literal>ParallelBitmapPopulate</></entry> + <entry>Waiting for the leader to populate the TidBitmap.</entry> + </row> + <row> + <entry><literal>ProcArrayGroupUpdate</></entry> + <entry>Waiting for group leader to clear transaction id at transaction end.</entry> + </row> + <row> + <entry><literal>SafeSnapshot</></entry> + <entry>Waiting for a snapshot for a <literal>READ ONLY DEFERRABLE</> transaction.</entry> + </row> + <row> + <entry><literal>SyncRep</></entry> + <entry>Waiting for confirmation from remote server during synchronous replication.</entry> + </row> + <row> + <entry morerows="2"><literal>Timeout</></entry> + <entry><literal>BaseBackupThrottle</></entry> + <entry>Waiting during base backup when throttling activity.</entry> + </row> + <row> + <entry><literal>PgSleep</></entry> + <entry>Waiting in process that called <function>pg_sleep</>.</entry> + </row> + <row> + <entry><literal>RecoveryApplyDelay</></entry> + <entry>Waiting to apply WAL at recovery because it is delayed.</entry> + </row> + <row> + <entry morerows="65"><literal>IO</></entry> + <entry><literal>BufFileRead</></entry> + <entry>Waiting for a read from a buffered file.</entry> + </row> + <row> + <entry><literal>BufFileWrite</></entry> + <entry>Waiting for a write to a buffered file.</entry> + </row> + <row> + <entry><literal>ControlFileRead</></entry> + <entry>Waiting for a read from the control file.</entry> + </row> + <row> + <entry><literal>ControlFileSync</></entry> + <entry>Waiting for the control file to reach stable storage.</entry> + </row> + <row> + <entry><literal>ControlFileSyncUpdate</></entry> + <entry>Waiting for an update to the control file to reach stable storage.</entry> + </row> + <row> + <entry><literal>ControlFileWrite</></entry> + <entry>Waiting for a write to the control file.</entry> + </row> + <row> + <entry><literal>ControlFileWriteUpdate</></entry> + <entry>Waiting for a write to update the control file.</entry> + </row> + <row> + <entry><literal>CopyFileRead</></entry> + <entry>Waiting for a read during a file copy operation.</entry> + </row> + <row> + <entry><literal>CopyFileWrite</></entry> + <entry>Waiting for a write during a file copy operation.</entry> + </row> + <row> + <entry><literal>DataFileExtend</></entry> + <entry>Waiting for a relation data file to be extended.</entry> + </row> + <row> + <entry><literal>DataFileFlush</></entry> + <entry>Waiting for a relation data file to reach stable storage.</entry> + </row> + <row> + <entry><literal>DataFileImmediateSync</></entry> + <entry>Waiting for an immediate synchronization of a relation data file to stable storage.</entry> + </row> + <row> + <entry><literal>DataFilePrefetch</></entry> + <entry>Waiting for an asynchronous prefetch from a relation data file.</entry> + </row> + <row> + <entry><literal>DataFileRead</></entry> + <entry>Waiting for a read from a relation data file.</entry> + </row> + <row> + <entry><literal>DataFileSync</></entry> + <entry>Waiting for changes to a relation data file to reach stable storage.</entry> + </row> + <row> + <entry><literal>DataFileTruncate</></entry> + <entry>Waiting for a relation data file to be truncated.</entry> + </row> + <row> + <entry><literal>DataFileWrite</></entry> + <entry>Waiting for a write to a relation data file.</entry> + </row> + <row> + <entry><literal>DSMFillZeroWrite</></entry> + <entry>Waiting to write zero bytes to a dynamic shared memory backing file.</entry> + </row> + <row> + <entry><literal>LockFileAddToDataDirRead</></entry> + <entry>Waiting for a read while adding a line to the data directory lock file.</entry> + </row> + <row> + <entry><literal>LockFileAddToDataDirSync</></entry> + <entry>Waiting for data to reach stable storage while adding a line to the data directory lock file.</entry> + </row> + <row> + <entry><literal>LockFileAddToDataDirWrite</></entry> + <entry>Waiting for a write while adding a line to the data directory lock file.</entry> + </row> + <row> + <entry><literal>LockFileCreateRead</></entry> + <entry>Waiting to read while creating the data directory lock file.</entry> + </row> + <row> + <entry><literal>LockFileCreateSync</></entry> + <entry>Waiting for data to reach stable storage while creating the data directory lock file.</entry> + </row> + <row> + <entry><literal>LockFileCreateWrite</></entry> + <entry>Waiting for a write while creating the data directory lock file.</entry> + </row> + <row> + <entry><literal>LockFileReCheckDataDirRead</></entry> + <entry>Waiting for a read during recheck of the data directory lock file.</entry> + </row> + <row> + <entry><literal>LogicalRewriteCheckpointSync</></entry> + <entry>Waiting for logical rewrite mappings to reach stable storage during a checkpoint.</entry> + </row> + <row> + <entry><literal>LogicalRewriteMappingSync</></entry> + <entry>Waiting for mapping data to reach stable storage during a logical rewrite.</entry> + </row> + <row> + <entry><literal>LogicalRewriteMappingWrite</></entry> + <entry>Waiting for a write of mapping data during a logical rewrite.</entry> + </row> + <row> + <entry><literal>LogicalRewriteSync</></entry> + <entry>Waiting for logical rewrite mappings to reach stable storage.</entry> + </row> + <row> + <entry><literal>LogicalRewriteWrite</></entry> + <entry>Waiting for a write of logical rewrite mappings.</entry> + </row> + <row> + <entry><literal>RelationMapRead</></entry> + <entry>Waiting for a read of the relation map file.</entry> + </row> + <row> + <entry><literal>RelationMapSync</></entry> + <entry>Waiting for the relation map file to reach stable storage.</entry> + </row> + <row> + <entry><literal>RelationMapWrite</></entry> + <entry>Waiting for a write to the relation map file.</entry> + </row> + <row> + <entry><literal>ReorderBufferRead</></entry> + <entry>Waiting for a read during reorder buffer management.</entry> + </row> + <row> + <entry><literal>ReorderBufferWrite</></entry> + <entry>Waiting for a write during reorder buffer management.</entry> + </row> + <row> + <entry><literal>ReorderLogicalMappingRead</></entry> + <entry>Waiting for a read of a logical mapping during reorder buffer management.</entry> + </row> + <row> + <entry><literal>ReplicationSlotRead</></entry> + <entry>Waiting for a read from a replication slot control file.</entry> + </row> + <row> + <entry><literal>ReplicationSlotRestoreSync</></entry> + <entry>Waiting for a replication slot control file to reach stable storage while restoring it to memory.</entry> + </row> + <row> + <entry><literal>ReplicationSlotSync</></entry> + <entry>Waiting for a replication slot control file to reach stable storage.</entry> + </row> + <row> + <entry><literal>ReplicationSlotWrite</></entry> + <entry>Waiting for a write to a replication slot control file.</entry> + </row> + <row> + <entry><literal>SLRUFlushSync</></entry> + <entry>Waiting for SLRU data to reach stable storage during a checkpoint or database shutdown.</entry> + </row> + <row> + <entry><literal>SLRURead</></entry> + <entry>Waiting for a read of an SLRU page.</entry> + </row> + <row> + <entry><literal>SLRUSync</></entry> + <entry>Waiting for SLRU data to reach stable storage following a page write.</entry> + </row> + <row> + <entry><literal>SLRUWrite</></entry> + <entry>Waiting for a write of an SLRU page.</entry> + </row> + <row> + <entry><literal>SnapbuildRead</></entry> + <entry>Waiting for a read of a serialized historical catalog snapshot.</entry> + </row> + <row> + <entry><literal>SnapbuildSync</></entry> + <entry>Waiting for a serialized historical catalog snapshot to reach stable storage.</entry> + </row> + <row> + <entry><literal>SnapbuildWrite</></entry> + <entry>Waiting for a write of a serialized historical catalog snapshot.</entry> + </row> + <row> + <entry><literal>TimelineHistoryFileSync</></entry> + <entry>Waiting for a timeline history file received via streaming replication to reach stable storage.</entry> + </row> + <row> + <entry><literal>TimelineHistoryFileWrite</></entry> + <entry>Waiting for a write of a timeline history file received via streaming replication.</entry> + </row> + <row> + <entry><literal>TimelineHistoryRead</></entry> + <entry>Waiting for a read of a timeline history file.</entry> + </row> + <row> + <entry><literal>TimelineHistorySync</></entry> + <entry>Waiting for a newly created timeline history file to reach stable storage.</entry> + </row> + <row> + <entry><literal>TimelineHistoryWrite</></entry> + <entry>Waiting for a write of a newly created timeline history file.</entry> + </row> + <row> + <entry><literal>TwophaseFileRead</></entry> + <entry>Waiting for a read of a two phase state file.</entry> + </row> + <row> + <entry><literal>TwophaseFileSync</></entry> + <entry>Waiting for a two phase state file to reach stable storage.</entry> + </row> + <row> + <entry><literal>TwophaseFileWrite</></entry> + <entry>Waiting for a write of a two phase state file.</entry> + </row> + <row> + <entry><literal>WALBootstrapSync</></entry> + <entry>Waiting for WAL to reach stable storage during bootstrapping.</entry> + </row> + <row> + <entry><literal>WALBootstrapWrite</></entry> + <entry>Waiting for a write of a WAL page during bootstrapping.</entry> + </row> + <row> + <entry><literal>WALCopyRead</></entry> + <entry>Waiting for a read when creating a new WAL segment by copying an existing one.</entry> + </row> + <row> + <entry><literal>WALCopySync</></entry> + <entry>Waiting a new WAL segment created by copying an existing one to reach stable storage.</entry> + </row> + <row> + <entry><literal>WALCopyWrite</></entry> + <entry>Waiting for a write when creating a new WAL segment by copying an existing one.</entry> + </row> + <row> + <entry><literal>WALInitSync</></entry> + <entry>Waiting for a newly initialized WAL file to reach stable storage.</entry> + </row> + <row> + <entry><literal>WALInitWrite</></entry> + <entry>Waiting for a write while initializing a new WAL file.</entry> + </row> + <row> + <entry><literal>WALRead</></entry> + <entry>Waiting for a read from a WAL file.</entry> + </row> + <row> + <entry><literal>WALSenderTimelineHistoryRead</></entry> + <entry>Waiting for a read from a timeline history file during walsender timeline command.</entry> + </row> + <row> + <entry><literal>WALSyncMethodAssign</></entry> + <entry>Waiting for data to reach stable storage while assigning WAL sync method.</entry> + </row> + <row> + <entry><literal>WALWrite</></entry> + <entry>Waiting for a write to a WAL file.</entry> + </row> </tbody> </tgroup> </table> @@ -1108,7 +1587,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i pid | wait_event_type | wait_event ------+-----------------+--------------- 2540 | Lock | relation - 6644 | LWLockNamed | ProcArrayLock + 6644 | LWLock | ProcArrayLock (2 rows) </programlisting> </para> @@ -1186,41 +1665,130 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i <row> <entry><structfield>state</></entry> <entry><type>text</></entry> - <entry>Current WAL sender state</entry> + <entry>Current WAL sender state. + Possible values are: + <itemizedlist> + <listitem> + <para> + <literal>startup</>: This WAL sender is starting up. + </para> + </listitem> + <listitem> + <para> + <literal>catchup</>: This WAL sender's connected standby is + catching up with the primary. + </para> + </listitem> + <listitem> + <para> + <literal>streaming</>: This WAL sender is streaming changes + after its connected standby server has caught up with the primary. + </para> + </listitem> + <listitem> + <para> + <literal>backup</>: This WAL sender is sending a backup. + </para> + </listitem> + <listitem> + <para> + <literal>stopping</>: This WAL sender is stopping. + </para> + </listitem> + </itemizedlist> + </entry> </row> <row> - <entry><structfield>sent_location</></entry> + <entry><structfield>sent_lsn</></entry> <entry><type>pg_lsn</></entry> - <entry>Last transaction log position sent on this connection</entry> + <entry>Last write-ahead log location sent on this connection</entry> </row> <row> - <entry><structfield>write_location</></entry> + <entry><structfield>write_lsn</></entry> <entry><type>pg_lsn</></entry> - <entry>Last transaction log position written to disk by this standby + <entry>Last write-ahead log location written to disk by this standby server</entry> </row> <row> - <entry><structfield>flush_location</></entry> + <entry><structfield>flush_lsn</></entry> <entry><type>pg_lsn</></entry> - <entry>Last transaction log position flushed to disk by this standby + <entry>Last write-ahead log location flushed to disk by this standby server</entry> </row> <row> - <entry><structfield>replay_location</></entry> + <entry><structfield>replay_lsn</></entry> <entry><type>pg_lsn</></entry> - <entry>Last transaction log position replayed into the database on this + <entry>Last write-ahead log location replayed into the database on this standby server</entry> </row> <row> + <entry><structfield>write_lag</></entry> + <entry><type>interval</></entry> + <entry>Time elapsed between flushing recent WAL locally and receiving + notification that this standby server has written it (but not yet + flushed it or applied it). This can be used to gauge the delay that + <literal>synchronous_commit</literal> level + <literal>remote_write</literal> incurred while committing if this + server was configured as a synchronous standby.</entry> + </row> + <row> + <entry><structfield>flush_lag</></entry> + <entry><type>interval</></entry> + <entry>Time elapsed between flushing recent WAL locally and receiving + notification that this standby server has written and flushed it + (but not yet applied it). This can be used to gauge the delay that + <literal>synchronous_commit</literal> level + <literal>remote_flush</literal> incurred while committing if this + server was configured as a synchronous standby.</entry> + </row> + <row> + <entry><structfield>replay_lag</></entry> + <entry><type>interval</></entry> + <entry>Time elapsed between flushing recent WAL locally and receiving + notification that this standby server has written, flushed and + applied it. This can be used to gauge the delay that + <literal>synchronous_commit</literal> level + <literal>remote_apply</literal> incurred while committing if this + server was configured as a synchronous standby.</entry> + </row> + <row> <entry><structfield>sync_priority</></entry> <entry><type>integer</></entry> <entry>Priority of this standby server for being chosen as the - synchronous standby</entry> + synchronous standby in a priority-based synchronous replication. + This has no effect in a quorum-based synchronous replication.</entry> </row> <row> <entry><structfield>sync_state</></entry> <entry><type>text</></entry> - <entry>Synchronous state of this standby server</entry> + <entry>Synchronous state of this standby server. + Possible values are: + <itemizedlist> + <listitem> + <para> + <literal>async</>: This standby server is asynchronous. + </para> + </listitem> + <listitem> + <para> + <literal>potential</>: This standby server is now asynchronous, + but can potentially become synchronous if one of current + synchronous ones fails. + </para> + </listitem> + <listitem> + <para> + <literal>sync</>: This standby server is synchronous. + </para> + </listitem> + <listitem> + <para> + <literal>quorum</>: This standby server is considered as a candidate + for quorum standbys. + </para> + </listitem> + </itemizedlist> + </entry> </row> </tbody> </tgroup> @@ -1233,6 +1801,45 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i listed; no information is available about downstream standby servers. </para> + <para> + The lag times reported in the <structname>pg_stat_replication</structname> + view are measurements of the time taken for recent WAL to be written, + flushed and replayed and for the sender to know about it. These times + represent the commit delay that was (or would have been) introduced by each + synchronous commit level, if the remote server was configured as a + synchronous standby. For an asynchronous standby, the + <structfield>replay_lag</structfield> column approximates the delay + before recent transactions became visible to queries. If the standby + server has entirely caught up with the sending server and there is no more + WAL activity, the most recently measured lag times will continue to be + displayed for a short time and then show NULL. + </para> + + <para> + Lag times work automatically for physical replication. Logical decoding + plugins may optionally emit tracking messages; if they do not, the tracking + mechanism will simply display NULL lag. + </para> + + <note> + <para> + The reported lag times are not predictions of how long it will take for + the standby to catch up with the sending server assuming the current + rate of replay. Such a system would show similar times while new WAL is + being generated, but would differ when the sender becomes idle. In + particular, when the standby has caught up completely, + <structname>pg_stat_replication</structname> shows the time taken to + write, flush and replay the most recent reported WAL location rather than + zero as some users might expect. This is consistent with the goal of + measuring synchronous commit and transaction visibility delays for + recent write transactions. + To reduce confusion for users expecting a different model of lag, the + lag columns revert to NULL after a short time on a fully replayed idle + system. Monitoring systems should choose whether to represent this + as missing data, zero or continue to display the last known value. + </para> + </note> + <table id="pg-stat-wal-receiver-view" xreflabel="pg_stat_wal_receiver"> <title><structname>pg_stat_wal_receiver</structname> View</title> <tgroup cols="3"> @@ -1258,7 +1865,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i <row> <entry><structfield>receive_start_lsn</></entry> <entry><type>pg_lsn</></entry> - <entry>First transaction log position used when WAL receiver is + <entry>First write-ahead log location used when WAL receiver is started</entry> </row> <row> @@ -1269,16 +1876,16 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i <row> <entry><structfield>received_lsn</></entry> <entry><type>pg_lsn</></entry> - <entry>Last transaction log position already received and flushed to - disk, the initial value of this field being the first log position used + <entry>Last write-ahead log location already received and flushed to + disk, the initial value of this field being the first log location used when WAL receiver is started</entry> </row> <row> <entry><structfield>received_tli</></entry> <entry><type>integer</></entry> - <entry>Timeline number of last transaction log position received and + <entry>Timeline number of last write-ahead log location received and flushed to disk, the initial value of this field being the timeline - number of the first log position used when WAL receiver is started + number of the first log location used when WAL receiver is started </entry> </row> <row> @@ -1294,12 +1901,12 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i <row> <entry><structfield>latest_end_lsn</></entry> <entry><type>pg_lsn</></entry> - <entry>Last transaction log position reported to origin WAL sender</entry> + <entry>Last write-ahead log location reported to origin WAL sender</entry> </row> <row> <entry><structfield>latest_end_time</></entry> <entry><type>timestamp with time zone</></entry> - <entry>Time of last transaction log position reported to origin WAL sender</entry> + <entry>Time of last write-ahead log location reported to origin WAL sender</entry> </row> <row> <entry><structfield>slot_name</></entry> @@ -1324,6 +1931,79 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i connected server. </para> + <table id="pg-stat-subscription" xreflabel="pg_stat_subscription"> + <title><structname>pg_stat_subscription</structname> View</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Column</entry> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><structfield>subid</></entry> + <entry><type>oid</></entry> + <entry>OID of the subscription</entry> + </row> + <row> + <entry><structfield>subname</></entry> + <entry><type>text</></entry> + <entry>Name of the subscription</entry> + </row> + <row> + <entry><structfield>pid</></entry> + <entry><type>integer</></entry> + <entry>Process ID of the subscription worker process</entry> + </row> + <row> + <entry><structfield>relid</></entry> + <entry><type>Oid</></entry> + <entry>OID of the relation that the worker is synchronizing; null for the + main apply worker</entry> + </row> + <row> + <entry><structfield>received_lsn</></entry> + <entry><type>pg_lsn</></entry> + <entry>Last write-ahead log location received, the initial value of + this field being 0</entry> + </row> + <row> + <entry><structfield>last_msg_send_time</></entry> + <entry><type>timestamp with time zone</></entry> + <entry>Send time of last message received from origin WAL sender</entry> + </row> + <row> + <entry><structfield>last_msg_receipt_time</></entry> + <entry><type>timestamp with time zone</></entry> + <entry>Receipt time of last message received from origin WAL sender + </entry> + </row> + <row> + <entry><structfield>latest_end_lsn</></entry> + <entry><type>pg_lsn</></entry> + <entry>Last write-ahead log location reported to origin WAL sender + </entry> + </row> + <row> + <entry><structfield>latest_end_time</></entry> + <entry><type>timestamp with time zone</></entry> + <entry>Time of last write-ahead log location reported to origin WAL + sender</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + The <structname>pg_stat_subscription</structname> view will contain one + row per subscription for main worker (with null PID if the worker is + not running), and additional rows for workers handling the initial data + copy of the subscribed tables. + </para> + <table id="pg-stat-ssl-view" xreflabel="pg_stat_ssl"> <title><structname>pg_stat_ssl</structname> View</title> <tgroup cols="3"> @@ -2739,7 +3419,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid, Currently, the <ulink url="https://en.wikipedia.org/wiki/DTrace">DTrace</ulink> utility is supported, which, at the time of this writing, is available - on Solaris, OS X, FreeBSD, NetBSD, and Oracle Linux. The + on Solaris, macOS, FreeBSD, NetBSD, and Oracle Linux. The <ulink url="http://sourceware.org/systemtap/">SystemTap</ulink> project for Linux provides a DTrace equivalent and can also be used. Supporting other dynamic tracing utilities is theoretically possible by changing the definitions for @@ -3054,14 +3734,14 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid, <entry>Probe that fires when a dirty WAL buffer write is complete.</entry> </row> <row> - <entry><literal>xlog-insert</literal></entry> + <entry><literal>wal-insert</literal></entry> <entry><literal>(unsigned char, unsigned char)</literal></entry> <entry>Probe that fires when a WAL record is inserted. arg0 is the resource manager (rmid) for the record. arg1 contains the info flags.</entry> </row> <row> - <entry><literal>xlog-switch</literal></entry> + <entry><literal>wal-switch</literal></entry> <entry><literal>()</literal></entry> <entry>Probe that fires when a WAL segment switch is requested.</entry> </row> @@ -3129,55 +3809,49 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid, </row> <row> <entry><literal>lwlock-acquire</literal></entry> - <entry><literal>(char *, int, LWLockMode)</literal></entry> + <entry><literal>(char *, LWLockMode)</literal></entry> <entry>Probe that fires when an LWLock has been acquired. arg0 is the LWLock's tranche. - arg1 is the LWLock's offset within its tranche. - arg2 is the requested lock mode, either exclusive or shared.</entry> + arg1 is the requested lock mode, either exclusive or shared.</entry> </row> <row> <entry><literal>lwlock-release</literal></entry> - <entry><literal>(char *, int)</literal></entry> + <entry><literal>(char *)</literal></entry> <entry>Probe that fires when an LWLock has been released (but note that any released waiters have not yet been awakened). - arg0 is the LWLock's tranche. - arg1 is the LWLock's offset within its tranche.</entry> + arg0 is the LWLock's tranche.</entry> </row> <row> <entry><literal>lwlock-wait-start</literal></entry> - <entry><literal>(char *, int, LWLockMode)</literal></entry> + <entry><literal>(char *, LWLockMode)</literal></entry> <entry>Probe that fires when an LWLock was not immediately available and a server process has begun to wait for the lock to become available. arg0 is the LWLock's tranche. - arg1 is the LWLock's offset within its tranche. - arg2 is the requested lock mode, either exclusive or shared.</entry> + arg1 is the requested lock mode, either exclusive or shared.</entry> </row> <row> <entry><literal>lwlock-wait-done</literal></entry> - <entry><literal>(char *, int, LWLockMode)</literal></entry> + <entry><literal>(char *, LWLockMode)</literal></entry> <entry>Probe that fires when a server process has been released from its wait for an LWLock (it does not actually have the lock yet). arg0 is the LWLock's tranche. - arg1 is the LWLock's offset within its tranche. - arg2 is the requested lock mode, either exclusive or shared.</entry> + arg1 is the requested lock mode, either exclusive or shared.</entry> </row> <row> <entry><literal>lwlock-condacquire</literal></entry> - <entry><literal>(char *, int, LWLockMode)</literal></entry> + <entry><literal>(char *, LWLockMode)</literal></entry> <entry>Probe that fires when an LWLock was successfully acquired when the caller specified no waiting. arg0 is the LWLock's tranche. - arg1 is the LWLock's offset within its tranche. - arg2 is the requested lock mode, either exclusive or shared.</entry> + arg1 is the requested lock mode, either exclusive or shared.</entry> </row> <row> <entry><literal>lwlock-condacquire-fail</literal></entry> - <entry><literal>(char *, int, LWLockMode)</literal></entry> + <entry><literal>(char *, LWLockMode)</literal></entry> <entry>Probe that fires when an LWLock was not successfully acquired when the caller specified no waiting. arg0 is the LWLock's tranche. - arg1 is the LWLock's offset within its tranche. - arg2 is the requested lock mode, either exclusive or shared.</entry> + arg1 is the requested lock mode, either exclusive or shared.</entry> </row> <row> <entry><literal>lock-wait-start</literal></entry> diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml index 78cd6ce773..b6a52b19d1 100644 --- a/doc/src/sgml/mvcc.sgml +++ b/doc/src/sgml/mvcc.sgml @@ -774,7 +774,9 @@ ERROR: could not serialize access due to read/write dependencies among transact locks into a single relation-level predicate lock because the predicate lock table is short of memory, an increase in the rate of serialization failures may occur. You can avoid this by increasing - <xref linkend="guc-max-pred-locks-per-transaction">. + <xref linkend="guc-max-pred-locks-per-transaction">, + <xref linkend="guc-max-pred-locks-per-relation">, and/or + <xref linkend="guc-max-pred-locks-per-page">. </para> </listitem> <listitem> @@ -932,7 +934,8 @@ ERROR: could not serialize access due to read/write dependencies among transact <para> Acquired by <command>VACUUM</command> (without <option>FULL</option>), - <command>ANALYZE</>, <command>CREATE INDEX CONCURRENTLY</>, and + <command>ANALYZE</>, <command>CREATE INDEX CONCURRENTLY</>, + <command>CREATE STATISTICS</> and <command>ALTER TABLE VALIDATE</command> and other <command>ALTER TABLE</command> variants (for full details see <xref linkend="SQL-ALTERTABLE">). @@ -976,7 +979,8 @@ ERROR: could not serialize access due to read/write dependencies among transact </para> <para> - Acquired by <command>CREATE TRIGGER</command> and many forms of + Acquired by <command>CREATE COLLATION</command>, + <command>CREATE TRIGGER</command>, and many forms of <command>ALTER TABLE</command> (see <xref linkend="SQL-ALTERTABLE">). </para> </listitem> diff --git a/doc/src/sgml/pageinspect.sgml b/doc/src/sgml/pageinspect.sgml index 96ac82afef..3809c4e7f9 100644 --- a/doc/src/sgml/pageinspect.sgml +++ b/doc/src/sgml/pageinspect.sgml @@ -20,7 +20,7 @@ </para> <sect2> - <title>Functions</title> + <title>General Functions</title> <variablelist> <varlistentry> @@ -79,12 +79,55 @@ test=# SELECT * FROM page_header(get_raw_page('pg_class', 0)); lsn | checksum | flags | lower | upper | special | pagesize | version | prune_xid -----------+----------+--------+-------+-------+---------+----------+---------+----------- - 0/24A1B50 | 1 | 1 | 232 | 368 | 8192 | 8192 | 4 | 0 + 0/24A1B50 | 0 | 1 | 232 | 368 | 8192 | 8192 | 4 | 0 </screen> The returned columns correspond to the fields in the <structname>PageHeaderData</> struct. See <filename>src/include/storage/bufpage.h</> for details. - </para> + </para> + + <para> + The <structfield>checksum</structfield> field is the checksum stored in + the page, which might be incorrect if the page is somehow corrupted. If + data checksums are not enabled for this instance, then the value stored + is meaningless. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <function>page_checksum(page bytea, blkno int4) returns smallint</function> + <indexterm> + <primary>page_checksum</primary> + </indexterm> + </term> + + <listitem> + <para> + <function>page_checksum</function> computes the checksum for the page, as if + it was located at the given block. + </para> + + <para> + A page image obtained with <function>get_raw_page</function> should be + passed as argument. For example: +<screen> +test=# SELECT page_checksum(get_raw_page('pg_class', 0), 0); + page_checksum +--------------- + 13443 +</screen> + Note that the checksum depends on the block number, so matching block + numbers should be passed (except when doing esoteric debugging). + </para> + + <para> + The checksum computed with this function can be compared with + the <structfield>checksum</structfield> result field of the + function <function>page_header</function>. If data checksums are + enabled for this instance, then the two values should be equal. + </para> </listitem> </varlistentry> @@ -166,7 +209,36 @@ test=# SELECT * FROM heap_page_item_attrs(get_raw_page('pg_class', 0), 'pg_class </para> </listitem> </varlistentry> - + + <varlistentry> + <term> + <function>fsm_page_contents(page bytea) returns text</function> + <indexterm> + <primary>fsm_page_contents</primary> + </indexterm> + </term> + + <listitem> + <para> + <function>fsm_page_contents</function> shows the internal node structure + of a FSM page. The output is a multiline string, with one line per + node in the binary tree within the page. Only those nodes that are not + zero are printed. The so-called "next" pointer, which points to the + next slot to be returned from the page, is also printed. + </para> + <para> + See <filename>src/backend/storage/freespace/README</> for more + information on the structure of an FSM page. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2> + <title>B-tree Functions</title> + + <variablelist> <varlistentry> <term> <function>bt_metap(relname text) returns record</function> @@ -270,6 +342,44 @@ test=# SELECT * FROM bt_page_items('pg_cast_oid_index', 1); <varlistentry> <term> + <function>bt_page_items(page bytea) returns setof record</function> + <indexterm> + <primary>bt_page_items</primary> + </indexterm> + </term> + + <listitem> + <para> + It is also possible to pass a page to <function>bt_page_items</function> + as a <type>bytea</> value. A page image obtained + with <function>get_raw_page</function> should be passed as argument. So + the last example could also be rewritten like this: +<screen> +test=# SELECT * FROM bt_page_items(get_raw_page('pg_cast_oid_index', 1)); + itemoffset | ctid | itemlen | nulls | vars | data +------------+---------+---------+-------+------+------------- + 1 | (0,1) | 12 | f | f | 23 27 00 00 + 2 | (0,2) | 12 | f | f | 24 27 00 00 + 3 | (0,3) | 12 | f | f | 25 27 00 00 + 4 | (0,4) | 12 | f | f | 26 27 00 00 + 5 | (0,5) | 12 | f | f | 27 27 00 00 + 6 | (0,6) | 12 | f | f | 28 27 00 00 + 7 | (0,7) | 12 | f | f | 29 27 00 00 + 8 | (0,8) | 12 | f | f | 2a 27 00 00 +</screen> + All the other details are the same as explained in the previous item. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2> + <title>BRIN Functions</title> + + <variablelist> + <varlistentry> + <term> <function>brin_page_type(page bytea) returns text</function> <indexterm> <primary>brin_page_type</primary> @@ -327,7 +437,7 @@ test=# SELECT * FROM brin_metapage_info(get_raw_page('brinidx', 0)); identifiers in a <acronym>BRIN</acronym> index range map page. For example: <screen> -test=# SELECT * FROM brin_revmap_data(get_raw_page('brinidx', 2)) limit 5; +test=# SELECT * FROM brin_revmap_data(get_raw_page('brinidx', 2)) LIMIT 5; pages --------- (6,137) @@ -371,7 +481,13 @@ test=# SELECT * FROM brin_page_items(get_raw_page('brinidx', 5), </para> </listitem> </varlistentry> + </variablelist> + </sect2> + <sect2> + <title>GIN Functions</title> + + <variablelist> <varlistentry> <term> <function>gin_metapage_info(page bytea) returns record</function> @@ -439,7 +555,7 @@ test=# SELECT * FROM gin_page_opaque_info(get_raw_page('gin_index', 2)); <function>gin_leafpage_items</function> returns information about the data stored in a <acronym>GIN</acronym> leaf page. For example: <screen> -test=# SELECT first_tid, nbytes, tids[0:5] as some_tids +test=# SELECT first_tid, nbytes, tids[0:5] AS some_tids FROM gin_leafpage_items(get_raw_page('gin_test_idx', 2)); first_tid | nbytes | some_tids -----------+--------+---------------------------------------------------------- @@ -455,26 +571,147 @@ test=# SELECT first_tid, nbytes, tids[0:5] as some_tids </para> </listitem> </varlistentry> + </variablelist> + </sect2> + <sect2> + <title>Hash Functions</title> + + <variablelist> <varlistentry> <term> - <function>fsm_page_contents(page bytea) returns text</function> + <function>hash_page_type(page bytea) returns text</function> <indexterm> - <primary>fsm_page_contents</primary> + <primary>hash_page_type</primary> </indexterm> </term> <listitem> <para> - <function>fsm_page_contents</function> shows the internal node structure - of a FSM page. The output is a multiline string, with one line per - node in the binary tree within the page. Only those nodes that are not - zero are printed. The so-called "next" pointer, which points to the - next slot to be returned from the page, is also printed. + <function>hash_page_type</function> returns page type of + the given <acronym>HASH</acronym> index page. For example: +<screen> +test=# SELECT hash_page_type(get_raw_page('con_hash_index', 0)); + hash_page_type +---------------- + metapage +</screen> </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <function>hash_page_stats(page bytea) returns setof record</function> + <indexterm> + <primary>hash_page_stats</primary> + </indexterm> + </term> + + <listitem> <para> - See <filename>src/backend/storage/freespace/README</> for more - information on the structure of an FSM page. + <function>hash_page_stats</function> returns information about + a bucket or overflow page of a <acronym>HASH</acronym> index. + For example: +<screen> +test=# SELECT * FROM hash_page_stats(get_raw_page('con_hash_index', 1)); +-[ RECORD 1 ]---+----------- +live_items | 407 +dead_items | 0 +page_size | 8192 +free_size | 8 +hasho_prevblkno | 4096 +hasho_nextblkno | 8474 +hasho_bucket | 0 +hasho_flag | 66 +hasho_page_id | 65408 +</screen> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <function>hash_page_items(page bytea) returns setof record</function> + <indexterm> + <primary>hash_page_items</primary> + </indexterm> + </term> + + <listitem> + <para> + <function>hash_page_items</function> returns information about + the data stored in a bucket or overflow page of a <acronym>HASH</acronym> + index page. For example: +<screen> +test=# SELECT * FROM hash_page_items(get_raw_page('con_hash_index', 1)) LIMIT 5; + itemoffset | ctid | data +------------+-----------+------------ + 1 | (899,77) | 1053474816 + 2 | (897,29) | 1053474816 + 3 | (894,207) | 1053474816 + 4 | (892,159) | 1053474816 + 5 | (890,111) | 1053474816 +</screen> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <function>hash_bitmap_info(index oid, blkno int) returns record</function> + <indexterm> + <primary>hash_bitmap_info</primary> + </indexterm> + </term> + + <listitem> + <para> + <function>hash_bitmap_info</function> shows the status of a bit + in the bitmap page for a particular overflow page of <acronym>HASH</acronym> + index. For example: +<screen> +test=# SELECT * FROM hash_bitmap_info('con_hash_index', 2052); + bitmapblkno | bitmapbit | bitstatus +-------------+-----------+----------- + 65 | 3 | t +</screen> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <function>hash_metapage_info(page bytea) returns record</function> + <indexterm> + <primary>hash_metapage_info</primary> + </indexterm> + </term> + + <listitem> + <para> + <function>hash_metapage_info</function> returns information stored + in meta page of a <acronym>HASH</acronym> index. For example: +<screen> +test=# SELECT * FROM hash_metapage_info(get_raw_page('con_hash_index', 0)); +-[ RECORD 1 ]----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- +magic | 105121344 +version | 3 +ntuples | 500500 +ffactor | 40 +bsize | 8152 +bmsize | 4096 +bmshift | 15 +maxbucket | 12512 +highmask | 16383 +lowmask | 8191 +ovflpoint | 28 +firstfree | 1204 +nmaps | 1 +procid | 450 +spares | {0,0,0,0,0,0,1,1,1,1,1,1,1,1,3,4,4,4,45,55,58,59,508,567,628,704,1193,1202,1204,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0} +mapp | {65,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0} +</screen> </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/parallel.sgml b/doc/src/sgml/parallel.sgml new file mode 100644 index 0000000000..a65129078c --- /dev/null +++ b/doc/src/sgml/parallel.sgml @@ -0,0 +1,529 @@ +<!-- doc/src/sgml/parallel.sgml --> + + <chapter id="parallel-query"> + <title>Parallel Query</title> + + <indexterm zone="parallel-query"> + <primary>parallel query</primary> + </indexterm> + + <para> + <productname>PostgreSQL</> can devise query plans which can leverage + multiple CPUs in order to answer queries faster. This feature is known + as parallel query. Many queries cannot benefit from parallel query, either + due to limitations of the current implementation or because there is no + imaginable query plan which is any faster than the serial query plan. + However, for queries that can benefit, the speedup from parallel query + is often very significant. Many queries can run more than twice as fast + when using parallel query, and some queries can run four times faster or + even more. Queries that touch a large amount of data but return only a + few rows to the user will typically benefit most. This chapter explains + some details of how parallel query works and in which situations it can be + used so that users who wish to make use of it can understand what to expect. + </para> + + <sect1 id="how-parallel-query-works"> + <title>How Parallel Query Works</title> + + <para> + When the optimizer determines that parallel query is the fastest execution + strategy for a particular query, it will create a query plan which includes + a <firstterm>Gather node</firstterm>. Here is a simple example: + +<screen> +EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%'; + QUERY PLAN +------------------------------------------------------------------------------------- + Gather (cost=1000.00..217018.43 rows=1 width=97) + Workers Planned: 2 + -> Parallel Seq Scan on pgbench_accounts (cost=0.00..216018.33 rows=1 width=97) + Filter: (filler ~~ '%x%'::text) +(4 rows) +</screen> + </para> + + <para> + In all cases, the <literal>Gather</literal> node will have exactly one + child plan, which is the portion of the plan that will be executed in + parallel. If the <literal>Gather</> node is at the very top of the plan + tree, then the entire query will execute in parallel. If it is somewhere + else in the plan tree, then only the portion of the plan below it will run + in parallel. In the example above, the query accesses only one table, so + there is only one plan node other than the <literal>Gather</> node itself; + since that plan node is a child of the <literal>Gather</> node, it will + run in parallel. + </para> + + <para> + <link linkend="using-explain">Using EXPLAIN</>, you can see the number of + workers chosen by the planner. When the <literal>Gather</> node is reached + during query execution, the process which is implementing the user's + session will request a number of <link linkend="bgworker">background + worker processes</link> equal to the number + of workers chosen by the planner. The total number of background + workers that can exist at any one time is limited by both + <xref linkend="guc-max-worker-processes"> and + <xref linkend="guc-max-parallel-workers">, so it is possible for a + parallel query to run with fewer workers than planned, or even with + no workers at all. The optimal plan may depend on the number of workers + that are available, so this can result in poor query performance. If this + occurrence is frequent, considering increasing + <varname>max_worker_processes</> and <varname>max_parallel_workers</> + so that more workers can be run simultaneously or alternatively reducing + <xref linkend="guc-max-parallel-workers-per-gather"> so that the planner + requests fewer workers. + </para> + + <para> + Every background worker process which is successfully started for a given + parallel query will execute the portion of the plan below + the <literal>Gather</> node. The leader will also execute that portion + of the plan, but it has an additional responsibility: it must also read + all of the tuples generated by the workers. When the parallel portion of + the plan generates only a small number of tuples, the leader will often + behave very much like an additional worker, speeding up query execution. + Conversely, when the parallel portion of the plan generates a large number + of tuples, the leader may be almost entirely occupied with reading the + tuples generated by the workers and performing any further processing + steps which are required by plan nodes above the level of the + <literal>Gather</literal> node. In such cases, the leader will do very + little of the work of executing the parallel portion of the plan. + </para> + </sect1> + + <sect1 id="when-can-parallel-query-be-used"> + <title>When Can Parallel Query Be Used?</title> + + <para> + There are several settings which can cause the query planner not to + generate a parallel query plan under any circumstances. In order for + any parallel query plans whatsoever to be generated, the following + settings must be configured as indicated. + </para> + + <itemizedlist> + <listitem> + <para> + <xref linkend="guc-max-parallel-workers-per-gather"> must be set to a + value which is greater than zero. This is a special case of the more + general principle that no more workers should be used than the number + configured via <varname>max_parallel_workers_per_gather</varname>. + </para> + </listitem> + + <listitem> + <para> + <xref linkend="guc-dynamic-shared-memory-type"> must be set to a + value other than <literal>none</>. Parallel query requires dynamic + shared memory in order to pass data between cooperating processes. + </para> + </listitem> + </itemizedlist> + + <para> + In addition, the system must not be running in single-user mode. Since + the entire database system is running in single process in this situation, + no background workers will be available. + </para> + + <para> + Even when it is in general possible for parallel query plans to be + generated, the planner will not generate them for a given query + if any of the following are true: + </para> + + <itemizedlist> + <listitem> + <para> + The query writes any data or locks any database rows. If a query + contains a data-modifying operation either at the top level or within + a CTE, no parallel plans for that query will be generated. This is a + limitation of the current implementation which could be lifted in a + future release. + </para> + </listitem> + + <listitem> + <para> + The query might be suspended during execution. In any situation in + which the system thinks that partial or incremental execution might + occur, no parallel plan is generated. For example, a cursor created + using <link linkend="sql-declare">DECLARE CURSOR</link> will never use + a parallel plan. Similarly, a PL/pgSQL loop of the form + <literal>FOR x IN query LOOP .. END LOOP</literal> will never use a + parallel plan, because the parallel query system is unable to verify + that the code in the loop is safe to execute while parallel query is + active. + </para> + </listitem> + + <listitem> + <para> + The query uses any function marked <literal>PARALLEL UNSAFE</literal>. + Most system-defined functions are <literal>PARALLEL SAFE</literal>, + but user-defined functions are marked <literal>PARALLEL + UNSAFE</literal> by default. See the discussion of + <xref linkend="parallel-safety">. + </para> + </listitem> + + <listitem> + <para> + The query is running inside of another query that is already parallel. + For example, if a function called by a parallel query issues an SQL + query itself, that query will never use a parallel plan. This is a + limitation of the current implementation, but it may not be desirable + to remove this limitation, since it could result in a single query + using a very large number of processes. + </para> + </listitem> + + <listitem> + <para> + The transaction isolation level is serializable. This is + a limitation of the current implementation. + </para> + </listitem> + </itemizedlist> + + <para> + Even when parallel query plan is generated for a particular query, there + are several circumstances under which it will be impossible to execute + that plan in parallel at execution time. If this occurs, the leader + will execute the portion of the plan below the <literal>Gather</> + node entirely by itself, almost as if the <literal>Gather</> node were + not present. This will happen if any of the following conditions are met: + </para> + + <itemizedlist> + <listitem> + <para> + No background workers can be obtained because of the limitation that + the total number of background workers cannot exceed + <xref linkend="guc-max-worker-processes">. + </para> + </listitem> + + <listitem> + <para> + No background workers can be obtained because of the limitation that + the total number of background workers launched for purposes of + parallel query cannot exceed <xref linkend="guc-max-parallel-workers">. + </para> + </listitem> + + <listitem> + <para> + The client sends an Execute message with a non-zero fetch count. + See the discussion of the + <link linkend="protocol-flow-ext-query">extended query protocol</link>. + Since <link linkend="libpq">libpq</link> currently provides no way to + send such a message, this can only occur when using a client that + does not rely on libpq. If this is a frequent + occurrence, it may be a good idea to set + <xref linkend="guc-max-parallel-workers-per-gather"> in sessions + where it is likely, so as to avoid generating query plans that may + be suboptimal when run serially. + </para> + </listitem> + + <listitem> + <para> + A prepared statement is executed using a <literal>CREATE TABLE .. AS + EXECUTE ..</literal> statement. This construct converts what otherwise + would have been a read-only operation into a read-write operation, + making it ineligible for parallel query. + </para> + </listitem> + + <listitem> + <para> + The transaction isolation level is serializable. This situation + does not normally arise, because parallel query plans are not + generated when the transaction isolation level is serializable. + However, it can happen if the transaction isolation level is changed to + serializable after the plan is generated and before it is executed. + </para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="parallel-plans"> + <title>Parallel Plans</title> + + <para> + Because each worker executes the parallel portion of the plan to + completion, it is not possible to simply take an ordinary query plan + and run it using multiple workers. Each worker would produce a full + copy of the output result set, so the query would not run any faster + than normal but would produce incorrect results. Instead, the parallel + portion of the plan must be what is known internally to the query + optimizer as a <firstterm>partial plan</>; that is, it must be constructed + so that each process which executes the plan will generate only a + subset of the output rows in such a way that each required output row + is guaranteed to be generated by exactly one of the cooperating processes. + </para> + + <sect2 id="parallel-scans"> + <title>Parallel Scans</title> + + <para> + The following types of parallel-aware table scans are currently supported. + + <itemizedlist> + <listitem> + <para> + In a <emphasis>parallel sequential scan</>, the table's blocks will + be divided among the cooperating processes. Blocks are handed out one + at a time, so that access to the table remains sequential. + </para> + </listitem> + <listitem> + <para> + In a <emphasis>parallel bitmap heap scan</>, one process is chosen + as the leader. That process performs a scan of one or more indexes + and builds a bitmap indicating which table blocks need to be visited. + These blocks are then divided among the cooperating processes as in + a parallel sequential scan. In other words, the heap scan is performed + in parallel, but the underlying index scan is not. + </para> + </listitem> + <listitem> + <para> + In a <emphasis>parallel index scan</> or <emphasis>parallel index-only + scan</>, the cooperating processes take turns reading data from the + index. Currently, parallel index scans are supported only for + btree indexes. Each process will claim a single index block and will + scan and return all tuples referenced by that block; other process can + at the same time be returning tuples from a different index block. + The results of a parallel btree scan are returned in sorted order + within each worker process. + </para> + </listitem> + </itemizedlist> + + Only the scan types listed above may be used for a scan on the driving + table within a parallel plan. Other scan types, such as parallel scans of + non-btree indexes, may be supported in the future. + </para> + </sect2> + + <sect2 id="parallel-joins"> + <title>Parallel Joins</title> + + <para> + Just as in a non-parallel plan, the driving table may be joined to one or + more other tables using a nested loop, hash join, or merge join. The + inner side of the join may be any kind of non-parallel plan that is + otherwise supported by the planner provided that it is safe to run within + a parallel worker. For example, if a nested loop join is chosen, the + inner plan may be an index scan which looks up a value taken from the outer + side of the join. + </para> + + <para> + Each worker will execute the inner side of the join in full. This is + typically not a problem for nested loops, but may be inefficient for + cases involving hash or merge joins. For example, for a hash join, this + restriction means that an identical hash table is built in each worker + process, which works fine for joins against small tables but may not be + efficient when the inner table is large. For a merge join, it might mean + that each worker performs a separate sort of the inner relation, which + could be slow. Of course, in cases where a parallel plan of this type + would be inefficient, the query planner will normally choose some other + plan (possibly one which does not use parallelism) instead. + </para> + </sect2> + + <sect2 id="parallel-aggregation"> + <title>Parallel Aggregation</title> + <para> + <productname>PostgreSQL</> supports parallel aggregation by aggregating in + two stages. First, each process participating in the parallel portion of + the query performs an aggregation step, producing a partial result for + each group of which that process is aware. This is reflected in the plan + as a <literal>Partial Aggregate</> node. Second, the partial results are + transferred to the leader via the <literal>Gather</> node. Finally, the + leader re-aggregates the results across all workers in order to produce + the final result. This is reflected in the plan as a + <literal>Finalize Aggregate</> node. + </para> + + <para> + Because the <literal>Finalize Aggregate</> node runs on the leader + process, queries which produce a relatively large number of groups in + comparison to the number of input rows will appear less favorable to the + query planner. For example, in the worst-case scenario the number of + groups seen by the <literal>Finalize Aggregate</> node could be as many as + the number of input rows which were seen by all worker processes in the + <literal>Partial Aggregate</> stage. For such cases, there is clearly + going to be no performance benefit to using parallel aggregation. The + query planner takes this into account during the planning process and is + unlikely to choose parallel aggregate in this scenario. + </para> + + <para> + Parallel aggregation is not supported in all situations. Each aggregate + must be <link linkend="parallel-safety">safe</> for parallelism and must + have a combine function. If the aggregate has a transition state of type + <literal>internal</>, it must have serialization and deserialization + functions. See <xref linkend="sql-createaggregate"> for more details. + Parallel aggregation is not supported if any aggregate function call + contains <literal>DISTINCT</> or <literal>ORDER BY</> clause and is also + not supported for ordered set aggregates or when the query involves + <literal>GROUPING SETS</>. It can only be used when all joins involved in + the query are also part of the parallel portion of the plan. + </para> + + </sect2> + + <sect2 id="parallel-plan-tips"> + <title>Parallel Plan Tips</title> + + <para> + If a query that is expected to do so does not produce a parallel plan, + you can try reducing <xref linkend="guc-parallel-setup-cost"> or + <xref linkend="guc-parallel-tuple-cost">. Of course, this plan may turn + out to be slower than the serial plan which the planner preferred, but + this will not always be the case. If you don't get a parallel + plan even with very small values of these settings (e.g. after setting + them both to zero), there may be some reason why the query planner is + unable to generate a parallel plan for your query. See + <xref linkend="when-can-parallel-query-be-used"> and + <xref linkend="parallel-safety"> for information on why this may be + the case. + </para> + + <para> + When executing a parallel plan, you can use <literal>EXPLAIN (ANALYZE, + VERBOSE)</literal> to display per-worker statistics for each plan node. + This may be useful in determining whether the work is being evenly + distributed between all plan nodes and more generally in understanding the + performance characteristics of the plan. + </para> + + </sect2> + </sect1> + + <sect1 id="parallel-safety"> + <title>Parallel Safety</title> + + <para> + The planner classifies operations involved in a query as either + <firstterm>parallel safe</>, <firstterm>parallel restricted</>, + or <firstterm>parallel unsafe</>. A parallel safe operation is one which + does not conflict with the use of parallel query. A parallel restricted + operation is one which cannot be performed in a parallel worker, but which + can be performed in the leader while parallel query is in use. Therefore, + parallel restricted operations can never occur below a <literal>Gather</> + node, but can occur elsewhere in a plan which contains a + <literal>Gather</> node. A parallel unsafe operation is one which cannot + be performed while parallel query is in use, not even in the leader. + When a query contains anything which is parallel unsafe, parallel query + is completely disabled for that query. + </para> + + <para> + The following operations are always parallel restricted. + </para> + + <itemizedlist> + <listitem> + <para> + Scans of common table expressions (CTEs). + </para> + </listitem> + + <listitem> + <para> + Scans of temporary tables. + </para> + </listitem> + + <listitem> + <para> + Scans of foreign tables, unless the foreign data wrapper has + an <literal>IsForeignScanParallelSafe</> API which indicates otherwise. + </para> + </listitem> + + <listitem> + <para> + Access to an <literal>InitPlan</> or <literal>SubPlan</>. + </para> + </listitem> + </itemizedlist> + + <sect2 id="parallel-labeling"> + <title>Parallel Labeling for Functions and Aggregates</title> + + <para> + The planner cannot automatically determine whether a user-defined + function or aggregate is parallel safe, parallel restricted, or parallel + unsafe, because this would require predicting every operation which the + function could possibly perform. In general, this is equivalent to the + Halting Problem and therefore impossible. Even for simple functions + where it conceivably be done, we do not try, since this would be expensive + and error-prone. Instead, all user-defined functions are assumed to + be parallel unsafe unless otherwise marked. When using + <xref linkend="sql-createfunction"> or + <xref linkend="sql-alterfunction">, markings can be set by specifying + <literal>PARALLEL SAFE</>, <literal>PARALLEL RESTRICTED</>, or + <literal>PARALLEL UNSAFE</> as appropriate. When using + <xref linkend="sql-createaggregate">, the + <literal>PARALLEL</> option can be specified with <literal>SAFE</>, + <literal>RESTRICTED</>, or <literal>UNSAFE</> as the corresponding value. + </para> + + <para> + Functions and aggregates must be marked <literal>PARALLEL UNSAFE</> if + they write to the database, access sequences, change the transaction state + even temporarily (e.g. a PL/pgSQL function which establishes an + <literal>EXCEPTION</> block to catch errors), or make persistent changes to + settings. Similarly, functions must be marked <literal>PARALLEL + RESTRICTED</> if they access temporary tables, client connection state, + cursors, prepared statements, or miscellaneous backend-local state which + the system cannot synchronize across workers. For example, + <literal>setseed</> and <literal>random</> are parallel restricted for + this last reason. + </para> + + <para> + In general, if a function is labeled as being safe when it is restricted or + unsafe, or if it is labeled as being restricted when it is in fact unsafe, + it may throw errors or produce wrong answers when used in a parallel query. + C-language functions could in theory exhibit totally undefined behavior if + mislabeled, since there is no way for the system to protect itself against + arbitrary C code, but in most likely cases the result will be no worse than + for any other function. If in doubt, it is probably best to label functions + as <literal>UNSAFE</>. + </para> + + <para> + If a function executed within a parallel worker acquires locks which are + not held by the leader, for example by querying a table not referenced in + the query, those locks will be released at worker exit, not end of + transaction. If you write a function which does this, and this behavior + difference is important to you, mark such functions as + <literal>PARALLEL RESTRICTED</literal> + to ensure that they execute only in the leader. + </para> + + <para> + Note that the query planner does not consider deferring the evaluation of + parallel-restricted functions or aggregates involved in the query in + order to obtain a superior plan. So, for example, if a <literal>WHERE</> + clause applied to a particular table is parallel restricted, the query + planner will not consider placing the scan of that table below a + <literal>Gather</> node. In some cases, it would be + possible (and perhaps even efficient) to include the scan of that table in + the parallel portion of the query and defer the evaluation of the + <literal>WHERE</> clause so that it happens above the <literal>Gather</> + node. However, the planner does not do this. + </para> + + </sect2> + + </sect1> + + </chapter> diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml index 2be518dff9..789be3d6a8 100644 --- a/doc/src/sgml/perform.sgml +++ b/doc/src/sgml/perform.sgml @@ -906,6 +906,8 @@ EXPLAIN ANALYZE SELECT * FROM tenk1 WHERE unique1 < 100 AND unique2 > 9000 <secondary>of the planner</secondary> </indexterm> + <sect2> + <title>Single-Column Statistics</title> <para> As we saw in the previous section, the query planner needs to estimate the number of rows retrieved by a query in order to make good choices @@ -1056,7 +1058,235 @@ WHERE tablename = 'road'; Further details about the planner's use of statistics can be found in <xref linkend="planner-stats-details">. </para> + </sect2> + + <sect2 id="planner-stats-extended"> + <title>Extended Statistics</title> + + <indexterm zone="planner-stats-extended"> + <primary>statistics</primary> + <secondary>of the planner</secondary> + </indexterm> + + <indexterm> + <primary>correlation</primary> + <secondary>in the query planner</secondary> + </indexterm> + + <indexterm> + <primary>pg_statistic_ext</primary> + </indexterm> + + <para> + It is common to see slow queries running bad execution plans because + multiple columns used in the query clauses are correlated. + The planner normally assumes that multiple conditions + are independent of each other, + an assumption that does not hold when column values are correlated. + Regular statistics, because of their per-individual-column nature, + cannot capture any knowledge about cross-column correlation. + However, <productname>PostgreSQL</> has the ability to compute + <firstterm>multivariate statistics</firstterm>, which can capture + such information. + </para> + + <para> + Because the number of possible column combinations is very large, + it's impractical to compute multivariate statistics automatically. + Instead, <firstterm>extended statistics objects</firstterm>, more often + called just <firstterm>statistics objects</>, can be created to instruct + the server to obtain statistics across interesting sets of columns. + </para> + + <para> + Statistics objects are created using + <xref linkend="sql-createstatistics">, which see for more details. + Creation of such an object merely creates a catalog entry expressing + interest in the statistics. Actual data collection is performed + by <command>ANALYZE</command> (either a manual command, or background + auto-analyze). The collected values can be examined in the + <link linkend="catalog-pg-statistic-ext"><structname>pg_statistic_ext</structname></link> + catalog. + </para> + + <para> + <command>ANALYZE</command> computes extended statistics based on the same + sample of table rows that it takes for computing regular single-column + statistics. Since the sample size is increased by increasing the + statistics target for the table or any of its columns (as described in + the previous section), a larger statistics target will normally result in + more accurate extended statistics, as well as more time spent calculating + them. + </para> + + <para> + The following subsections describe the types of extended statistics + that are currently supported. + </para> + + <sect3> + <title>Functional Dependencies</title> + + <para> + The simplest type of extended statistics tracks <firstterm>functional + dependencies</>, a concept used in definitions of database normal forms. + We say that column <structfield>b</> is functionally dependent on + column <structfield>a</> if knowledge of the value of + <structfield>a</> is sufficient to determine the value + of <structfield>b</>, that is there are no two rows having the same value + of <structfield>a</> but different values of <structfield>b</>. + In a fully normalized database, functional dependencies should exist + only on primary keys and superkeys. However, in practice many data sets + are not fully normalized for various reasons; intentional + denormalization for performance reasons is a common example. + Even in a fully normalized database, there may be partial correlation + between some columns, which can be expressed as partial functional + dependency. + </para> + + <para> + The existence of functional dependencies directly affects the accuracy + of estimates in certain queries. If a query contains conditions on + both the independent and the dependent column(s), the + conditions on the dependent columns do not further reduce the result + size; but without knowledge of the functional dependency, the query + planner will assume that the conditions are independent, resulting + in underestimating the result size. + </para> + + <para> + To inform the planner about functional dependencies, <command>ANALYZE</> + can collect measurements of cross-column dependency. Assessing the + degree of dependency between all sets of columns would be prohibitively + expensive, so data collection is limited to those groups of columns + appearing together in a statistics object defined with + the <literal>dependencies</> option. It is advisable to create + <literal>dependencies</> statistics only for column groups that are + strongly correlated, to avoid unnecessary overhead in both + <command>ANALYZE</> and later query planning. + </para> + + <para> + Here is an example of collecting functional-dependency statistics: +<programlisting> +CREATE STATISTICS stts (dependencies) ON zip, city FROM zipcodes; + +ANALYZE zipcodes; + +SELECT stxname, stxkeys, stxdependencies + FROM pg_statistic_ext + WHERE stxname = 'stts'; + stxname | stxkeys | stxdependencies +---------+---------+------------------------------------------ + stts | 1 5 | {"1 => 5": 1.000000, "5 => 1": 0.423130} +(1 row) +</programlisting> + Here it can be seen that column 1 (zip code) fully determines column + 5 (city) so the coefficient is 1.0, while city only determines zip code + about 42% of the time, meaning that there are many cities (58%) that are + represented by more than a single ZIP code. + </para> + + <para> + When computing the selectivity for a query involving functionally + dependent columns, the planner adjusts the per-condition selectivity + estimates using the dependency coefficients so as not to produce + an underestimate. + </para> + + <sect4> + <title>Limitations of Functional Dependencies</title> + + <para> + Functional dependencies are currently only applied when considering + simple equality conditions that compare columns to constant values. + They are not used to improve estimates for equality conditions + comparing two columns or comparing a column to an expression, nor for + range clauses, <literal>LIKE</> or any other type of condition. + </para> + + <para> + When estimating with functional dependencies, the planner assumes that + conditions on the involved columns are compatible and hence redundant. + If they are incompatible, the correct estimate would be zero rows, but + that possibility is not considered. For example, given a query like +<programlisting> +SELECT * FROM zipcodes WHERE city = 'San Francisco' AND zip = '94105'; +</programlisting> + the planner will disregard the <structfield>city</> clause as not + changing the selectivity, which is correct. However, it will make + the same assumption about +<programlisting> +SELECT * FROM zipcodes WHERE city = 'San Francisco' AND zip = '90210'; +</programlisting> + even though there will really be zero rows satisfying this query. + Functional dependency statistics do not provide enough information + to conclude that, however. + </para> + + <para> + In many practical situations, this assumption is usually satisfied; + for example, there might be a GUI in the application that only allows + selecting compatible city and zipcode values to use in a query. + But if that's not the case, functional dependencies may not be a viable + option. + </para> + </sect4> + </sect3> + + <sect3> + <title>Multivariate N-Distinct Counts</title> + + <para> + Single-column statistics store the number of distinct values in each + column. Estimates of the number of distinct values when combining more + than one column (for example, for <literal>GROUP BY a, b</literal>) are + frequently wrong when the planner only has single-column statistical + data, causing it to select bad plans. + </para> + + <para> + To improve such estimates, <command>ANALYZE</> can collect n-distinct + statistics for groups of columns. As before, it's impractical to do + this for every possible column grouping, so data is collected only for + those groups of columns appearing together in a statistics object + defined with the <literal>ndistinct</> option. Data will be collected + for each possible combination of two or more columns from the set of + listed columns. + </para> + + <para> + Continuing the previous example, the n-distinct counts in a + table of ZIP codes might look like the following: +<programlisting> +CREATE STATISTICS stts2 (ndistinct) ON zip, state, city FROM zipcodes; +ANALYZE zipcodes; + +SELECT stxkeys AS k, stxndistinct AS nd + FROM pg_statistic_ext + WHERE stxname = 'stts2'; +-[ RECORD 1 ]-------------------------------------------------------- +k | 1 2 5 +nd | {"1, 2": 33178, "1, 5": 33178, "2, 5": 27435, "1, 2, 5": 33178} +(1 row) +</programlisting> + This indicates that there are three combinations of columns that + have 33178 distinct values: ZIP code and state; ZIP code and city; + and ZIP code, city and state (the fact that they are all equal is + expected given that ZIP code alone is unique in this table). On the + other hand, the combination of city and state has only 27435 distinct + values. + </para> + + <para> + It's advisable to create <literal>ndistinct</> statistics objects only + on combinations of columns that are actually used for grouping, and + for which misestimation of the number of groups is resulting in bad + plans. Otherwise, the <command>ANALYZE</> cycles are just wasted. + </para> + </sect3> + </sect2> </sect1> <sect1 id="explicit-joins"> @@ -1654,7 +1884,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse; Increase <xref linkend="guc-max-wal-size"> and <xref linkend="guc-checkpoint-timeout"> ; this reduces the frequency of checkpoints, but increases the storage requirements of - <filename>/pg_xlog</>. + <filename>/pg_wal</>. </para> </listitem> diff --git a/doc/src/sgml/pgbuffercache.sgml b/doc/src/sgml/pgbuffercache.sgml index 6c5be94a4c..2e26d9e202 100644 --- a/doc/src/sgml/pgbuffercache.sgml +++ b/doc/src/sgml/pgbuffercache.sgml @@ -24,8 +24,9 @@ </para> <para> - By default public access is revoked from both of these, just in case there - are security issues lurking. + By default use is restricted to superusers and members of the + <literal>pg_read_all_stats</literal> role. Access may be granted to others + using <command>GRANT</command>. </para> <para> diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml index c4cefde4f7..bf514aacf3 100644 --- a/doc/src/sgml/pgcrypto.sgml +++ b/doc/src/sgml/pgcrypto.sgml @@ -1184,12 +1184,12 @@ gen_random_uuid() returns uuid <row> <entry>SHA224/256/384/512</entry> <entry>yes</entry> - <entry>yes (Note 1)</entry> + <entry>yes</entry> </row> <row> <entry>Other digest algorithms</entry> <entry>no</entry> - <entry>yes (Note 2)</entry> + <entry>yes (Note 1)</entry> </row> <row> <entry>Blowfish</entry> @@ -1199,7 +1199,7 @@ gen_random_uuid() returns uuid <row> <entry>AES</entry> <entry>yes</entry> - <entry>yes (Note 3)</entry> + <entry>yes</entry> </row> <row> <entry>DES/3DES/CAST5</entry> @@ -1232,23 +1232,11 @@ gen_random_uuid() returns uuid <orderedlist> <listitem> <para> - SHA2 algorithms were added to OpenSSL in version 0.9.8. For - older versions, <filename>pgcrypto</> will use built-in code. - </para> - </listitem> - <listitem> - <para> Any digest algorithm OpenSSL supports is automatically picked up. This is not possible with ciphers, which need to be supported explicitly. </para> </listitem> - <listitem> - <para> - AES is included in OpenSSL since version 0.9.7. For - older versions, <filename>pgcrypto</> will use built-in code. - </para> - </listitem> </orderedlist> </sect3> diff --git a/doc/src/sgml/pgfreespacemap.sgml b/doc/src/sgml/pgfreespacemap.sgml index a88cd52678..924d512f6a 100644 --- a/doc/src/sgml/pgfreespacemap.sgml +++ b/doc/src/sgml/pgfreespacemap.sgml @@ -16,8 +16,9 @@ </para> <para> - By default public access is revoked from the functions, just in case - there are security issues lurking. + By default use is restricted to superusers and members of the + <literal>pg_stat_scan_tables</literal> role. Access may be granted to others + using <command>GRANT</command>. </para> <para> diff --git a/doc/src/sgml/pgrowlocks.sgml b/doc/src/sgml/pgrowlocks.sgml index 4fae2fad98..b0cde6d01a 100644 --- a/doc/src/sgml/pgrowlocks.sgml +++ b/doc/src/sgml/pgrowlocks.sgml @@ -13,6 +13,12 @@ </para> <para> + By default use is restricted to superusers, members of the + <literal>pg_stat_scan_tables</literal> role, and users with + <literal>SELECT</literal> permissions on the table. + </para> + + <para> Functions of this module return information from the Coordinator that the session is currently connect to. To get information about a Datanode, you can diff --git a/doc/src/sgml/pgstandby.sgml b/doc/src/sgml/pgstandby.sgml index fb3f32eaaa..bf4edea9f1 100644 --- a/doc/src/sgml/pgstandby.sgml +++ b/doc/src/sgml/pgstandby.sgml @@ -22,7 +22,7 @@ <arg rep="repeat"><replaceable>option</replaceable></arg> <arg choice="plain"><replaceable>archivelocation</replaceable></arg> <arg choice="plain"><replaceable>nextwalfile</replaceable></arg> - <arg choice="plain"><replaceable>xlogfilepath</replaceable></arg> + <arg choice="plain"><replaceable>walfilepath</replaceable></arg> <arg choice="opt"><replaceable>restartwalfile</replaceable></arg> </cmdsynopsis> </refsynopsisdiv> @@ -363,7 +363,7 @@ recovery_end_command = 'del C:\pgsql.trigger.5442' The <literal>copy</> command on Windows sets the final file size before the file is completely copied, which would ordinarily confuse <application>pg_standby</application>. Therefore - <application>pg_standby</application> waits <literal>sleeptime</> + <application>pg_standby</application> waits <replaceable>sleeptime</> seconds once it sees the proper file size. GNUWin32's <literal>cp</> sets the file size only after the file copy is complete. </para> diff --git a/doc/src/sgml/pgstatstatements.sgml b/doc/src/sgml/pgstatstatements.sgml index f1fae7a5fe..97a16e0cd4 100644 --- a/doc/src/sgml/pgstatstatements.sgml +++ b/doc/src/sgml/pgstatstatements.sgml @@ -231,10 +231,11 @@ </table> <para> - For security reasons, non-superusers are not allowed to see the SQL - text or <structfield>queryid</structfield> of queries executed by other users. - They can see the statistics, however, if the view has been installed in their - database. + For security reasons, only superusers and members of the + <literal>pg_read_all_stats</literal> role are allowed to see the SQL text and + <structfield>queryid</structfield> of queries executed by other users. + Other users can see the statistics, however, if the view has been installed + in their database. </para> <para> @@ -249,11 +250,12 @@ </para> <para> - When a constant's value has been ignored for purposes of matching the - query to other queries, the constant is replaced by <literal>?</literal> - in the <structname>pg_stat_statements</> display. The rest of the query - text is that of the first query that had the particular - <structfield>queryid</> hash value associated with the + When a constant's value has been ignored for purposes of matching the query + to other queries, the constant is replaced by a parameter symbol, such + as <literal>$1</literal>, in the <structname>pg_stat_statements</> + display. + The rest of the query text is that of the first query that had the + particular <structfield>queryid</> hash value associated with the <structname>pg_stat_statements</> entry. </para> @@ -307,6 +309,18 @@ </para> <para> + The parameter symbols used to replace constants in + representative query texts start from the next number after the + highest <literal>$</><replaceable>n</> parameter in the original query + text, or <literal>$1</> if there was none. It's worth noting that in + some cases there may be hidden parameter symbols that affect this + numbering. For example, <application>PL/pgSQL</> uses hidden parameter + symbols to insert values of function local variables into queries, so that + a <application>PL/pgSQL</> statement like <literal>SELECT i + 1 INTO j</> + would have representative text like <literal>SELECT i + $2</>. + </para> + + <para> The representative query texts are kept in an external disk file, and do not consume shared memory. Therefore, even very lengthy query texts can be stored successfully. However, if many long query texts are @@ -486,13 +500,13 @@ bench=# SELECT query, calls, total_time, rows, 100.0 * shared_blks_hit / nullif(shared_blks_hit + shared_blks_read, 0) AS hit_percent FROM pg_stat_statements ORDER BY total_time DESC LIMIT 5; -[ RECORD 1 ]--------------------------------------------------------------------- -query | UPDATE pgbench_branches SET bbalance = bbalance + ? WHERE bid = ?; +query | UPDATE pgbench_branches SET bbalance = bbalance + $1 WHERE bid = $2; calls | 3000 total_time | 9609.00100000002 rows | 2836 hit_percent | 99.9778970000200936 -[ RECORD 2 ]--------------------------------------------------------------------- -query | UPDATE pgbench_tellers SET tbalance = tbalance + ? WHERE tid = ?; +query | UPDATE pgbench_tellers SET tbalance = tbalance + $1 WHERE tid = $2; calls | 3000 total_time | 8015.156 rows | 2990 @@ -504,7 +518,7 @@ total_time | 310.624 rows | 100000 hit_percent | 0.30395136778115501520 -[ RECORD 4 ]--------------------------------------------------------------------- -query | UPDATE pgbench_accounts SET abalance = abalance + ? WHERE aid = ?; +query | UPDATE pgbench_accounts SET abalance = abalance + $1 WHERE aid = $2; calls | 3000 total_time | 271.741999999997 rows | 3000 diff --git a/doc/src/sgml/pgstattuple.sgml b/doc/src/sgml/pgstattuple.sgml index b5e2ea7187..63412b03ef 100644 --- a/doc/src/sgml/pgstattuple.sgml +++ b/doc/src/sgml/pgstattuple.sgml @@ -13,6 +13,14 @@ </para> <para> + As these functions return detailed page-level information, only the superuser + has EXECUTE privileges on them upon installation. After the functions have + been installed, users may issue <command>GRANT</command> commands to change + the privileges on the functions to allow non-superusers to execute them. Members + of the <literal>pg_stat_scan_tables</literal> role are granted access by default. See + the description of the <xref linkend="sql-grant"> command for specifics. + </para> + <para> Functions of this module return information from the Coordinator that the session is currently connected to. To get information about a Datanode, you can use <command>EXECUTE DIRECT</command>. @@ -115,6 +123,16 @@ free_percent | 1.95 </tgroup> </table> + <note> + <para> + The <literal>table_len</literal> will always be greater than the sum + of the <literal>tuple_len</literal>, <literal>dead_tuple_len</literal> + and <literal>free_space</literal>. The difference is accounted for by + fixed page overhead, the per-page table of pointers to tuples, and + padding to ensure that tuples are correctly aligned. + </para> + </note> + <para> <function>pgstattuple</function> acquires only a read lock on the relation. So the results do not reflect an instantaneous snapshot; @@ -343,6 +361,101 @@ pending_tuples | 0 <varlistentry> <term> <indexterm> + <primary>pgstathashindex</primary> + </indexterm> + <function>pgstathashindex(regclass) returns record</> + </term> + + <listitem> + <para> + <function>pgstathashindex</function> returns a record showing information + about a HASH index. For example: +<programlisting> +test=> select * from pgstathashindex('con_hash_index'); +-[ RECORD 1 ]--+----------------- +version | 2 +bucket_pages | 33081 +overflow_pages | 0 +bitmap_pages | 1 +unused_pages | 32455 +live_items | 10204006 +dead_items | 0 +free_percent | 61.8005949100872 +</programlisting> + </para> + + <para> + The output columns are: + + <informaltable> + <tgroup cols="3"> + <thead> + <row> + <entry>Column</entry> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><structfield>version</structfield></entry> + <entry><type>integer</type></entry> + <entry>HASH version number</entry> + </row> + + <row> + <entry><structfield>bucket_pages</structfield></entry> + <entry><type>bigint</type></entry> + <entry>Number of bucket pages</entry> + </row> + + <row> + <entry><structfield>overflow_pages</structfield></entry> + <entry><type>bigint</type></entry> + <entry>Number of overflow pages</entry> + </row> + + <row> + <entry><structfield>bitmap_pages</structfield></entry> + <entry><type>bigint</type></entry> + <entry>Number of bitmap pages</entry> + </row> + + <row> + <entry><structfield>unused_pages</structfield></entry> + <entry><type>bigint</type></entry> + <entry>Number of unused pages</entry> + </row> + + <row> + <entry><structfield>live_items</structfield></entry> + <entry><type>bigint</type></entry> + <entry>Number of live tuples</entry> + </row> + + <row> + <entry><structfield>dead_tuples</structfield></entry> + <entry><type>bigint</type></entry> + <entry>Number of dead tuples</entry> + </row> + + <row> + <entry><structfield>free_percent</structfield></entry> + <entry><type>float</type></entry> + <entry>Percentage of free space</entry> + </row> + + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm> <primary>pg_relpages</primary> </indexterm> <function>pg_relpages(regclass) returns bigint</> diff --git a/doc/src/sgml/pgtrgm.sgml b/doc/src/sgml/pgtrgm.sgml index d362b03cf3..775a7b8be7 100644 --- a/doc/src/sgml/pgtrgm.sgml +++ b/doc/src/sgml/pgtrgm.sgml @@ -104,7 +104,7 @@ the second string a most similar word not a most similar substring. The range of the result is zero (indicating that the two strings are completely dissimilar) to one (indicating that the first string is - identical to one of the word of the second string). + identical to one of the words of the second string). </entry> </row> <row> diff --git a/doc/src/sgml/pgvisibility.sgml b/doc/src/sgml/pgvisibility.sgml index d764eff9a0..d466a3bce8 100644 --- a/doc/src/sgml/pgvisibility.sgml +++ b/doc/src/sgml/pgvisibility.sgml @@ -9,31 +9,33 @@ <para> The <filename>pg_visibility</> module provides a means for examining the - visibility map (VM) and page-level visibility information. It also - provides functions to check the integrity of the visibility map and to + visibility map (VM) and page-level visibility information of a table. + It also provides functions to check the integrity of a visibility map and to force it to be rebuilt. </para> <para> Three different bits are used to store information about page-level visibility. The all-visible bit in the visibility map indicates that every - tuple on a given page of a relation is visible to every current transaction. - The all-frozen bit in the visibility map indicates that every tuple on the - page is frozen; that is, no future vacuum will need to modify the page - until such time as a tuple is inserted, updated, deleted, or locked on - that page. The page-level <literal>PD_ALL_VISIBLE</literal> bit has the + tuple in the corresponding page of the relation is visible to every current + and future transaction. The all-frozen bit in the visibility map indicates + that every tuple in the page is frozen; that is, no future vacuum will need + to modify the page until such time as a tuple is inserted, updated, deleted, + or locked on that page. + The page header's <literal>PD_ALL_VISIBLE</literal> bit has the same meaning as the all-visible bit in the visibility map, but is stored - within the data page itself rather than a separate data structure. These - will normally agree, but the page-level bit can sometimes be set while the - visibility map bit is clear after a crash recovery; or they can disagree - because of a change which occurs after <literal>pg_visibility</> examines - the visibility map and before it examines the data page. Any event which - causes data corruption can also cause these bits to disagree. + within the data page itself rather than in a separate data structure. + These two bits will normally agree, but the page's all-visible bit can + sometimes be set while the visibility map bit is clear after a crash + recovery. The reported values can also disagree because of a change that + occurs after <literal>pg_visibility</> examines the visibility map and + before it examines the data page. Any event that causes data corruption + can also cause these bits to disagree. </para> <para> - Functions which display information about <literal>PD_ALL_VISIBLE</> - are much more costly than those which only consult the visibility map, + Functions that display information about <literal>PD_ALL_VISIBLE</> bits + are much more costly than those that only consult the visibility map, because they must read the relation's data blocks rather than only the (much smaller) visibility map. Functions that check the relation's data blocks are similarly expensive. @@ -44,7 +46,7 @@ <variablelist> <varlistentry> - <term><function>pg_visibility_map(regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean) returns record</function></term> + <term><function>pg_visibility_map(relation regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean) returns record</function></term> <listitem> <para> Returns the all-visible and all-frozen bits in the visibility map for @@ -54,40 +56,40 @@ </varlistentry> <varlistentry> - <term><function>pg_visibility(regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns record</function></term> + <term><function>pg_visibility(relation regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns record</function></term> <listitem> <para> Returns the all-visible and all-frozen bits in the visibility map for the given block of the given relation, plus the - <literal>PD_ALL_VISIBLE</> bit for that block. + <literal>PD_ALL_VISIBLE</> bit of that block. </para> </listitem> </varlistentry> <varlistentry> - <term><function>pg_visibility_map(regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean) returns setof record</function></term> + <term><function>pg_visibility_map(relation regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean) returns setof record</function></term> <listitem> <para> Returns the all-visible and all-frozen bits in the visibility map for - each block the given relation. + each block of the given relation. </para> </listitem> </varlistentry> <varlistentry> - <term><function>pg_visibility(regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns setof record</function></term> + <term><function>pg_visibility(relation regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns setof record</function></term> <listitem> <para> Returns the all-visible and all-frozen bits in the visibility map for - each block the given relation, plus the <literal>PD_ALL_VISIBLE</> - bit for each block. + each block of the given relation, plus the <literal>PD_ALL_VISIBLE</> + bit of each block. </para> </listitem> </varlistentry> <varlistentry> - <term><function>pg_visibility_map_summary(regclass, all_visible OUT bigint, all_frozen OUT bigint) returns record</function></term> + <term><function>pg_visibility_map_summary(relation regclass, all_visible OUT bigint, all_frozen OUT bigint) returns record</function></term> <listitem> <para> @@ -96,50 +98,52 @@ </para> </listitem> </varlistentry> - + <varlistentry> - <term><function>pg_check_frozen(regclass, t_ctid OUT tid) returns setof tid</function></term> + <term><function>pg_check_frozen(relation regclass, t_ctid OUT tid) returns setof tid</function></term> <listitem> <para> - Returns the TIDs of non-frozen tuples present in pages marked all-frozen + Returns the TIDs of non-frozen tuples stored in pages marked all-frozen in the visibility map. If this function returns a non-empty set of - TIDs, the database is corrupt. + TIDs, the visibility map is corrupt. </para> </listitem> </varlistentry> - - <varlistentry> - <term><function>pg_check_visible(regclass, t_ctid OUT tid) returns setof tid</function></term> + + <varlistentry> + <term><function>pg_check_visible(relation regclass, t_ctid OUT tid) returns setof tid</function></term> <listitem> <para> - Returns the TIDs of tuples which are not all-visible despite the fact - that the pages which contain them are marked as all-visible in the - visibility map. If this function returns a non-empty set of TIDs, the - database is corrupt. + Returns the TIDs of non-all-visible tuples stored in pages marked + all-visible in the visibility map. If this function returns a non-empty + set of TIDs, the visibility map is corrupt. </para> </listitem> </varlistentry> <varlistentry> - <term><function>pg_truncate_visibility_map(regclass) returns void</function></term> + <term><function>pg_truncate_visibility_map(relation regclass) returns void</function></term> <listitem> <para> - Truncates the visibility map for the given relation. This function - is only expected to be useful if you suspect that the visibility map - for the indicated relation is corrupt and wish to rebuild it. The first - <command>VACUUM</> executed on the given relation after this function - is executed will scan every page in the relation and rebuild the - visibility map. + Truncates the visibility map for the given relation. This function is + useful if you believe that the visibility map for the relation is + corrupt and wish to force rebuilding it. The first <command>VACUUM</> + executed on the given relation after this function is executed will scan + every page in the relation and rebuild the visibility map. (Until that + is done, queries will treat the visibility map as containing all zeroes.) </para> </listitem> </varlistentry> </variablelist> <para> - By default, these functions are not publicly executable. + By default, these functions are executable only by superusers and members of the + <literal>pg_stat_scan_tables</literal> role, with the exception of + <function>pg_truncate_visibility_map(relation regclass)</function> which can only + be executed by superusers. </para> </sect2> diff --git a/doc/src/sgml/planstats.sgml b/doc/src/sgml/planstats.sgml index 1a482d37f4..8caf297f85 100644 --- a/doc/src/sgml/planstats.sgml +++ b/doc/src/sgml/planstats.sgml @@ -94,7 +94,7 @@ EXPLAIN SELECT * FROM tenk1 WHERE unique1 < 1000; and the entry in this case is <function>scalarltsel</function>. The <function>scalarltsel</function> function retrieves the histogram for <structfield>unique1</structfield> from - <structname>pg_statistics</structname>. For manual queries it is more + <structname>pg_statistic</structname>. For manual queries it is more convenient to look in the simpler <structname>pg_stats</structname> view: @@ -445,7 +445,206 @@ rows = (outer_cardinality * inner_cardinality) * selectivity operator-specific selectivity functions are mostly found in <filename>src/backend/utils/adt/selfuncs.c</filename>. </para> + </sect1> + + <sect1 id="multivariate-statistics-examples"> + <title>Multivariate Statistics Examples</title> + + <indexterm> + <primary>row estimation</primary> + <secondary>multivariate</secondary> + </indexterm> + + <sect2> + <title>Functional Dependencies</title> + + <para> + Multivariate correlation can be demonstrated with a very simple data set + — a table with two columns, both containing the same values: + +<programlisting> +CREATE TABLE t (a INT, b INT); +INSERT INTO t SELECT i % 100, i % 100 FROM generate_series(1, 10000) s(i); +ANALYZE t; +</programlisting> + + As explained in <xref linkend="planner-stats">, the planner can determine + cardinality of <structname>t</structname> using the number of pages and + rows obtained from <structname>pg_class</structname>: + +<programlisting> +SELECT relpages, reltuples FROM pg_class WHERE relname = 't'; + + relpages | reltuples +----------+----------- + 45 | 10000 +</programlisting> + + The data distribution is very simple; there are only 100 distinct values + in each column, uniformly distributed. + </para> + + <para> + The following example shows the result of estimating a <literal>WHERE</> + condition on the <structfield>a</> column: + +<programlisting> +EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1; + QUERY PLAN +------------------------------------------------------------------------------- + Seq Scan on t (cost=0.00..170.00 rows=100 width=8) (actual rows=100 loops=1) + Filter: (a = 1) + Rows Removed by Filter: 9900 +</programlisting> + + The planner examines the condition and determines the selectivity + of this clause to be 1%. By comparing this estimate and the actual + number of rows, we see that the estimate is very accurate + (in fact exact, as the table is very small). Changing the + <literal>WHERE</> to use the <structfield>b</> column, an identical + plan is generated. But observe what happens if we apply the same + condition on both columns, combining them with <literal>AND</>: + +<programlisting> +EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1 AND b = 1; + QUERY PLAN +----------------------------------------------------------------------------- + Seq Scan on t (cost=0.00..195.00 rows=1 width=8) (actual rows=100 loops=1) + Filter: ((a = 1) AND (b = 1)) + Rows Removed by Filter: 9900 +</programlisting> + + The planner estimates the selectivity for each condition individually, + arriving at the same 1% estimates as above. Then it assumes that the + conditions are independent, and so it multiplies their selectivities, + producing a final selectivity estimate of just 0.01%. + This is a significant underestimate, as the actual number of rows + matching the conditions (100) is two orders of magnitude higher. + </para> + <para> + This problem can be fixed by creating a statistics object that + directs <command>ANALYZE</> to calculate functional-dependency + multivariate statistics on the two columns: + +<programlisting> +CREATE STATISTICS stts (dependencies) ON a, b FROM t; +ANALYZE t; +EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1 AND b = 1; + QUERY PLAN +------------------------------------------------------------------------------- + Seq Scan on t (cost=0.00..195.00 rows=100 width=8) (actual rows=100 loops=1) + Filter: ((a = 1) AND (b = 1)) + Rows Removed by Filter: 9900 +</programlisting> + </para> + </sect2> + + <sect2> + <title>Multivariate N-Distinct Counts</title> + + <para> + A similar problem occurs with estimation of the cardinality of sets of + multiple columns, such as the number of groups that would be generated by + a <command>GROUP BY</command> clause. When <command>GROUP BY</command> + lists a single column, the n-distinct estimate (which is visible as the + estimated number of rows returned by the HashAggregate node) is very + accurate: +<programlisting> +EXPLAIN (ANALYZE, TIMING OFF) SELECT COUNT(*) FROM t GROUP BY a; + QUERY PLAN +----------------------------------------------------------------------------------------- + HashAggregate (cost=195.00..196.00 rows=100 width=12) (actual rows=100 loops=1) + Group Key: a + -> Seq Scan on t (cost=0.00..145.00 rows=10000 width=4) (actual rows=10000 loops=1) +</programlisting> + But without multivariate statistics, the estimate for the number of + groups in a query with two columns in <command>GROUP BY</command>, as + in the following example, is off by an order of magnitude: +<programlisting> +EXPLAIN (ANALYZE, TIMING OFF) SELECT COUNT(*) FROM t GROUP BY a, b; + QUERY PLAN +-------------------------------------------------------------------------------------------- + HashAggregate (cost=220.00..230.00 rows=1000 width=16) (actual rows=100 loops=1) + Group Key: a, b + -> Seq Scan on t (cost=0.00..145.00 rows=10000 width=8) (actual rows=10000 loops=1) +</programlisting> + By redefining the statistics object to include n-distinct counts for the + two columns, the estimate is much improved: +<programlisting> +DROP STATISTICS stts; +CREATE STATISTICS stts (dependencies, ndistinct) ON a, b FROM t; +ANALYZE t; +EXPLAIN (ANALYZE, TIMING OFF) SELECT COUNT(*) FROM t GROUP BY a, b; + QUERY PLAN +-------------------------------------------------------------------------------------------- + HashAggregate (cost=220.00..221.00 rows=100 width=16) (actual rows=100 loops=1) + Group Key: a, b + -> Seq Scan on t (cost=0.00..145.00 rows=10000 width=8) (actual rows=10000 loops=1) +</programlisting> + </para> + + </sect2> </sect1> + <sect1 id="planner-stats-security"> + <title>Planner Statistics and Security</title> + + <para> + Access to the table <structname>pg_statistic</structname> is restricted to + superusers, so that ordinary users cannot learn about the contents of the + tables of other users from it. Some selectivity estimation functions will + use a user-provided operator (either the operator appearing in the query or + a related operator) to analyze the stored statistics. For example, in order + to determine whether a stored most common value is applicable, the + selectivity estimator will have to run the appropriate <literal>=</literal> + operator to compare the constant in the query to the stored value. + Thus the data in <structname>pg_statistic</structname> is potentially + passed to user-defined operators. An appropriately crafted operator can + intentionally leak the passed operands (for example, by logging them + or writing them to a different table), or accidentally leak them by showing + their values in error messages, in either case possibly exposing data from + <structname>pg_statistic</structname> to a user who should not be able to + see it. + </para> + + <para> + In order to prevent this, the following applies to all built-in selectivity + estimation functions. When planning a query, in order to be able to use + stored statistics, the current user must either + have <literal>SELECT</literal> privilege on the table or the involved + columns, or the operator used must be <literal>LEAKPROOF</literal> (more + accurately, the function that the operator is based on). If not, then the + selectivity estimator will behave as if no statistics are available, and + the planner will proceed with default or fall-back assumptions. + </para> + + <para> + If a user does not have the required privilege on the table or columns, + then in many cases the query will ultimately receive a permission-denied + error, in which case this mechanism is invisible in practice. But if the + user is reading from a security-barrier view, then the planner might wish + to check the statistics of an underlying table that is otherwise + inaccessible to the user. In that case, the operator should be leak-proof + or the statistics will not be used. There is no direct feedback about + that, except that the plan might be suboptimal. If one suspects that this + is the case, one could try running the query as a more privileged user, + to see if a different plan results. + </para> + + <para> + This restriction applies only to cases where the planner would need to + execute a user-defined operator on one or more values + from <structname>pg_statistic</structname>. Thus the planner is permitted + to use generic statistical information, such as the fraction of null values + or the number of distinct values in a column, regardless of access + privileges. + </para> + + <para> + Selectivity estimation functions contained in third-party extensions that + potentially operate on statistics with user-defined operators should follow + the same security rules. Consult the PostgreSQL source code for guidance. + </para> + </sect1> </chapter> diff --git a/doc/src/sgml/plhandler.sgml b/doc/src/sgml/plhandler.sgml index 0fc5d7b411..57a2a05ed2 100644 --- a/doc/src/sgml/plhandler.sgml +++ b/doc/src/sgml/plhandler.sgml @@ -26,7 +26,7 @@ language such as C, using the version-1 interface, and registered with <productname>PostgreSQL</productname> as taking no arguments and returning the type <type>language_handler</type>. This - special pseudotype identifies the function as a call handler and + special pseudo-type identifies the function as a call handler and prevents it from being called directly in SQL commands. For more details on C language calling conventions and dynamic loading, see <xref linkend="xfunc-c">. diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml index a1207652a2..09b4d54b72 100644 --- a/doc/src/sgml/plperl.sgml +++ b/doc/src/sgml/plperl.sgml @@ -27,8 +27,7 @@ <para> To install PL/Perl in a particular database, use - <literal>CREATE EXTENSION plperl</>, or from the shell command line use - <literal>createlang plperl <replaceable>dbname</></literal>. + <literal>CREATE EXTENSION plperl</>. </para> <tip> diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index be38b1e790..09019df698 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -4009,13 +4009,10 @@ CREATE OR REPLACE FUNCTION process_emp_audit() RETURNS TRIGGER AS $emp_audit$ -- IF (TG_OP = 'DELETE') THEN INSERT INTO emp_audit SELECT 'D', now(), user, OLD.*; - RETURN OLD; ELSIF (TG_OP = 'UPDATE') THEN INSERT INTO emp_audit SELECT 'U', now(), user, NEW.*; - RETURN NEW; ELSIF (TG_OP = 'INSERT') THEN INSERT INTO emp_audit SELECT 'I', now(), user, NEW.*; - RETURN NEW; END IF; RETURN NULL; -- result is ignored since this is an AFTER trigger END; @@ -4861,7 +4858,7 @@ a_output := a_output || $$ if v_$$ || referrer_keys.kind || $$ like '$$ <para> To aid the user in finding instances of simple but common problems before - they cause harm, <application>PL/PgSQL</> provides additional + they cause harm, <application>PL/pgSQL</> provides additional <replaceable>checks</>. When enabled, depending on the configuration, they can be used to emit either a <literal>WARNING</> or an <literal>ERROR</> during the compilation of a function. A function which has received @@ -5338,14 +5335,14 @@ SELECT * FROM cs_parse_url('http://foobar.com/query.cgi?baz'); <programlisting> CREATE OR REPLACE PROCEDURE cs_create_job(v_job_id IN INTEGER) IS a_running_job_count INTEGER; - PRAGMA AUTONOMOUS_TRANSACTION;<co id="co.plpgsql-porting-pragma"> + PRAGMA AUTONOMOUS_TRANSACTION; -- <co id="co.plpgsql-porting-pragma"> BEGIN - LOCK TABLE cs_jobs IN EXCLUSIVE MODE;<co id="co.plpgsql-porting-locktable"> + LOCK TABLE cs_jobs IN EXCLUSIVE MODE; -- <co id="co.plpgsql-porting-locktable"> SELECT count(*) INTO a_running_job_count FROM cs_jobs WHERE end_stamp IS NULL; IF a_running_job_count > 0 THEN - COMMIT; -- free lock<co id="co.plpgsql-porting-commit"> + COMMIT; -- free lock <co id="co.plpgsql-porting-commit"> raise_application_error(-20000, 'Unable to create a new job: a job is currently running.'); END IF; @@ -5412,7 +5409,7 @@ BEGIN SELECT count(*) INTO a_running_job_count FROM cs_jobs WHERE end_stamp IS NULL; IF a_running_job_count > 0 THEN - RAISE EXCEPTION 'Unable to create a new job: a job is currently running';<co id="co.plpgsql-porting-raise"> + RAISE EXCEPTION 'Unable to create a new job: a job is currently running'; -- <co id="co.plpgsql-porting-raise"> END IF; DELETE FROM cs_active_job; @@ -5421,7 +5418,7 @@ BEGIN BEGIN INSERT INTO cs_jobs (job_id, start_stamp) VALUES (v_job_id, now()); EXCEPTION - WHEN unique_violation THEN <co id="co.plpgsql-porting-exception"> + WHEN unique_violation THEN -- <co id="co.plpgsql-porting-exception"> -- don't worry if it already exists END; END; diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml index 905e757ab6..777a7ef780 100644 --- a/doc/src/sgml/plpython.sgml +++ b/doc/src/sgml/plpython.sgml @@ -14,8 +14,7 @@ <para> To install PL/Python in a particular database, use - <literal>CREATE EXTENSION plpythonu</>, or from the shell command line use - <literal>createlang plpythonu <replaceable>dbname</></literal> (but + <literal>CREATE EXTENSION plpythonu</> (but see also <xref linkend="plpython-python23">). </para> @@ -451,13 +450,13 @@ $$ LANGUAGE plpythonu; <para> SQL array values are passed into PL/Python as a Python list. To return an SQL array value out of a PL/Python function, return a - Python sequence, for example a list or tuple: + Python list: <programlisting> CREATE FUNCTION return_arr() RETURNS int[] AS $$ -return (1, 2, 3, 4, 5) +return [1, 2, 3, 4, 5] $$ LANGUAGE plpythonu; SELECT return_arr(); @@ -467,6 +466,34 @@ SELECT return_arr(); (1 row) </programlisting> + Multidimensional arrays are passed into PL/Python as nested Python lists. + A 2-dimensional array is a list of lists, for example. When returning + a multi-dimensional SQL array out of a PL/Python function, the inner + lists at each level must all be of the same size. For example: + +<programlisting> +CREATE FUNCTION test_type_conversion_array_int4(x int4[]) RETURNS int4[] AS $$ +plpy.info(x, type(x)) +return x +$$ LANGUAGE plpythonu; + +SELECT * FROM test_type_conversion_array_int4(ARRAY[[1,2,3],[4,5,6]]); +INFO: ([[1, 2, 3], [4, 5, 6]], <type 'list'>) + test_type_conversion_array_int4 +--------------------------------- + {{1,2,3},{4,5,6}} +(1 row) +</programlisting> + + Other Python sequences, like tuples, are also accepted for + backwards-compatibility with PostgreSQL versions 9.6 and below, when + multi-dimensional arrays were not supported. However, they are always + treated as one-dimensional arrays, because they are ambiguous with + composite types. For the same reason, when a composite type is used in a + multi-dimensional array, it must be represented by a tuple, rather than a + list. + </para> + <para> Note that in Python, strings are sequences, which can have undesirable effects that might be familiar to Python programmers: @@ -541,14 +568,19 @@ CREATE TYPE named_value AS ( CREATE FUNCTION make_pair (name text, value integer) RETURNS named_value AS $$ - return [ name, value ] - # or alternatively, as tuple: return ( name, value ) + return ( name, value ) + # or alternatively, as tuple: return [ name, value ] $$ LANGUAGE plpythonu; </programlisting> To return a SQL null for any column, insert <symbol>None</symbol> at the corresponding position. </para> + <para> + When an array of composite types is returned, it cannot be returned as a list, + because it is ambiguous whether the Python list represents a composite type, + or another array dimension. + </para> </listitem> </varlistentry> @@ -696,19 +728,6 @@ AS $$ $$ LANGUAGE plpythonu; </programlisting> - <warning> - <para> - Due to Python - <ulink url="http://bugs.python.org/issue1483133">bug #1483133</ulink>, - some debug versions of Python 2.4 - (configured and compiled with option <literal>--with-pydebug</literal>) - are known to crash the <productname>PostgreSQL</productname> server - when using an iterator to return a set result. - Unpatched versions of Fedora 4 contain this bug. - It does not happen in production versions of Python or on patched - versions of Fedora 4. - </para> - </warning> </para> </listitem> </varlistentry> @@ -1028,6 +1047,14 @@ rv = plpy.execute(plan, ["name"], 5) </para> <para> + Alternatively, you can call the <function>execute</function> method on + the plan object: +<programlisting> +rv = plan.execute(["name"], 5) +</programlisting> + </para> + + <para> Query parameters and result row fields are converted between PostgreSQL and Python data types as described in <xref linkend="plpython-data">. </para> @@ -1062,7 +1089,9 @@ $$ LANGUAGE plpythonu; as <literal>plpy.execute</literal> (except for the row limit) and returns a cursor object, which allows you to process large result sets in smaller chunks. As with <literal>plpy.execute</literal>, either a query string - or a plan object along with a list of arguments can be used. + or a plan object along with a list of arguments can be used, or + the <function>cursor</function> function can be called as a method of + the plan object. </para> <para> @@ -1106,7 +1135,7 @@ $$ LANGUAGE plpythonu; CREATE FUNCTION count_odd_prepared() RETURNS integer AS $$ odd = 0 plan = plpy.prepare("select num from largetable where num % $1 <> 0", ["integer"]) -rows = list(plpy.cursor(plan, [2])) +rows = list(plpy.cursor(plan, [2])) # or: = list(plan.cursor([2])) return len(rows) $$ LANGUAGE plpythonu; diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml index 720a9cc42f..321a46917e 100644 --- a/doc/src/sgml/pltcl.sgml +++ b/doc/src/sgml/pltcl.sgml @@ -66,10 +66,9 @@ directory if Tcl support is specified in the configuration step of the installation procedure. To install <application>PL/Tcl</> and/or <application>PL/TclU</> in a particular database, use the - <command>CREATE EXTENSION</> command or the - <command>createlang</command> program, for example - <literal>createlang pltcl <replaceable>dbname</></literal> or - <literal>createlang pltclu <replaceable>dbname</></literal>. + <command>CREATE EXTENSION</> command, for example + <literal>CREATE EXTENSION pltcl</literal> or + <literal>CREATE EXTENSION pltclu</literal>. </para> </sect1> @@ -94,11 +93,11 @@ $$ LANGUAGE pltcl; <para> The body of the function is simply a piece of Tcl script. - When the function is called, the argument values are passed as - variables <literal>$1</literal> ... <literal>$<replaceable>n</replaceable></literal> to the - Tcl script. The result is returned - from the Tcl code in the usual way, with a <literal>return</literal> - statement. + When the function is called, the argument values are passed to the + Tcl script as variables named <literal>1</literal> + ... <literal><replaceable>n</replaceable></literal>. The result is + returned from the Tcl code in the usual way, with + a <literal>return</literal> statement. </para> <para> @@ -173,17 +172,57 @@ $$ LANGUAGE pltcl; </para> <para> - There is currently no support for returning a composite-type - result value, nor for returning sets. + PL/Tcl functions can return composite-type results, too. To do this, + the Tcl code must return a list of column name/value pairs matching + the expected result type. Any column names omitted from the list + are returned as nulls, and an error is raised if there are unexpected + column names. Here is an example: + +<programlisting> +CREATE FUNCTION square_cube(in int, out squared int, out cubed int) AS $$ + return [list squared [expr {$1 * $1}] cubed [expr {$1 * $1 * $1}]] +$$ LANGUAGE pltcl; +</programlisting> </para> + <tip> + <para> + The result list can be made from an array representation of the + desired tuple with the <literal>array get</> Tcl command. For example: + +<programlisting> +CREATE FUNCTION raise_pay(employee, delta int) RETURNS employee AS $$ + set 1(salary) [expr {$1(salary) + $2}] + return [array get 1] +$$ LANGUAGE pltcl; +</programlisting> + </para> + </tip> + <para> - <application>PL/Tcl</> does not currently have full support for - domain types: it treats a domain the same as the underlying scalar - type. This means that constraints associated with the domain will - not be enforced. This is not an issue for function arguments, but - it is a hazard if you declare a <application>PL/Tcl</> function - as returning a domain type. + PL/Tcl functions can return sets. To do this, the Tcl code should + call <function>return_next</function> once per row to be returned, + passing either the appropriate value when returning a scalar type, + or a list of column name/value pairs when returning a composite type. + Here is an example returning a scalar type: + +<programlisting> +CREATE FUNCTION sequence(int, int) RETURNS SETOF int AS $$ + for {set i $1} {$i < $2} {incr i} { + return_next $i + } +$$ LANGUAGE pltcl; +</programlisting> + + and here is one returning a composite type: + +<programlisting> +CREATE FUNCTION table_of_squares(int, int) RETURNS TABLE (x int, x2 int) AS $$ + for {set i $1} {$i < $2} {incr i} { + return_next [list x $i x2 [expr {$i * $i}]] + } +$$ LANGUAGE pltcl; +</programlisting> </para> </sect1> @@ -195,10 +234,9 @@ $$ LANGUAGE pltcl; The argument values supplied to a PL/Tcl function's code are simply the input arguments converted to text form (just as if they had been displayed by a <command>SELECT</> statement). Conversely, the - <literal>return</> - command will accept any string that is acceptable input format for - the function's declared return type. So, within the PL/Tcl function, - all values are just text strings. + <literal>return</> and <literal>return_next</> commands will accept + any string that is acceptable input format for the function's declared + result type, or for the specified column of a composite result type. </para> </sect1> @@ -296,20 +334,22 @@ $$ LANGUAGE pltcl; If the command is a <command>SELECT</> statement, the values of the result columns are placed into Tcl variables named after the columns. If the <literal>-array</> option is given, the column values are - instead stored into the named associative array, with the - column names used as array indexes. + instead stored into elements of the named associative array, with the + column names used as array indexes. In addition, the current row + number within the result (counting from zero) is stored into the array + element named <quote><literal>.tupno</></quote>, unless that name is + in use as a column name in the result. </para> <para> If the command is a <command>SELECT</> statement and no <replaceable>loop-body</> script is given, then only the first row of results are stored into - Tcl variables; remaining rows, if any, are ignored. No storing occurs - if the - query returns no rows. (This case can be detected by checking the - result of <function>spi_exec</function>.) For example: + Tcl variables or array elements; remaining rows, if any, are ignored. + No storing occurs if the query returns no rows. (This case can be + detected by checking the result of <function>spi_exec</function>.) + For example: <programlisting> spi_exec "SELECT count(*) AS cnt FROM pg_proc" </programlisting> - will set the Tcl variable <literal>$cnt</> to the number of rows in the <structname>pg_proc</> system catalog. </para> @@ -317,15 +357,15 @@ spi_exec "SELECT count(*) AS cnt FROM pg_proc" If the optional <replaceable>loop-body</> argument is given, it is a piece of Tcl script that is executed once for each row in the query result. (<replaceable>loop-body</> is ignored if the given - command is not a <command>SELECT</>.) The values of the current row's columns - are stored into Tcl variables before each iteration. For example: - + command is not a <command>SELECT</>.) + The values of the current row's columns + are stored into Tcl variables or array elements before each iteration. + For example: <programlisting> spi_exec -array C "SELECT * FROM pg_class" { elog DEBUG "have table $C(relname)" } </programlisting> - will print a log message for every row of <literal>pg_class</>. This feature works similarly to other Tcl looping constructs; in particular <literal>continue</> and <literal>break</> work in the @@ -436,6 +476,20 @@ $$ LANGUAGE pltcl; </varlistentry> <varlistentry> + <term><function>subtransaction</function> <replaceable>command</replaceable></term> + <listitem> + <para> + The Tcl script contained in <replaceable>command</replaceable> is + executed within a SQL subtransaction. If the script returns an + error, that entire subtransaction is rolled back before returning the + error out to the surrounding Tcl code. + See <xref linkend="pltcl-subtransactions"> for more details and an + example. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><function>quote</> <replaceable>string</replaceable></term> <listitem> <para> @@ -667,21 +721,35 @@ SELECT 'doesn''t' AS ret <para> The return value from a trigger procedure can be one of the strings - <literal>OK</> or <literal>SKIP</>, or a list as returned by the - <literal>array get</> Tcl command. If the return value is <literal>OK</>, - the operation (<command>INSERT</>/<command>UPDATE</>/<command>DELETE</>) that fired the trigger will proceed + <literal>OK</> or <literal>SKIP</>, or a list of column name/value pairs. + If the return value is <literal>OK</>, + the operation (<command>INSERT</>/<command>UPDATE</>/<command>DELETE</>) + that fired the trigger will proceed normally. <literal>SKIP</> tells the trigger manager to silently suppress the operation for this row. If a list is returned, it tells PL/Tcl to - return a modified row to the trigger manager. This is only meaningful + return a modified row to the trigger manager; the contents of the + modified row are specified by the column names and values in the list. + Any columns not mentioned in the list are set to null. + Returning a modified row is only meaningful for row-level <literal>BEFORE</> <command>INSERT</> or <command>UPDATE</> - triggers for which the modified row will be inserted instead of the one + triggers, for which the modified row will be inserted instead of the one given in <varname>$NEW</>; or for row-level <literal>INSTEAD OF</> <command>INSERT</> or <command>UPDATE</> triggers where the returned row - is used to support <command>INSERT RETURNING</> and - <command>UPDATE RETURNING</> commands. The return value is ignored for - other types of triggers. + is used as the source data for <command>INSERT RETURNING</> or + <command>UPDATE RETURNING</> clauses. + In row-level <literal>BEFORE</> <command>DELETE</> or <literal>INSTEAD + OF</> <command>DELETE</> triggers, returning a modified row has the same + effect as returning <literal>OK</>, that is the operation proceeds. + The trigger return value is ignored for all other types of triggers. </para> + <tip> + <para> + The result list can be made from an array representation of the + modified tuple with the <literal>array get</> Tcl command. + </para> + </tip> + <para> Here's a little example trigger procedure that forces an integer value in a table to keep track of the number of updates that are performed on the @@ -794,18 +862,22 @@ CREATE EVENT TRIGGER tcl_a_snitch ON ddl_command_start EXECUTE PROCEDURE tclsnit either by executing some invalid operation or by generating an error using the Tcl <function>error</function> command or PL/Tcl's <function>elog</function> command. Such errors can be caught - within Tcl using the Tcl <function>catch</function> command. If they - are not caught but are allowed to propagate out to the top level of - execution of the PL/Tcl function, they turn into database errors. + within Tcl using the Tcl <function>catch</function> command. If an + error is not caught but is allowed to propagate out to the top level of + execution of the PL/Tcl function, it is reported as a SQL error in the + function's calling query. </para> <para> - Conversely, database errors that occur within PL/Tcl's + Conversely, SQL errors that occur within PL/Tcl's <function>spi_exec</function>, <function>spi_prepare</function>, and <function>spi_execp</function> commands are reported as Tcl errors, so they are catchable by Tcl's <function>catch</function> command. - Again, if they propagate out to the top level without being caught, - they turn back into database errors. + (Each of these PL/Tcl commands runs its SQL operation in a + subtransaction, which is rolled back on error, so that any + partially-completed operation is automatically cleaned up.) + Again, if an error propagates out to the top level without being caught, + it turns back into a SQL error. </para> <para> @@ -852,49 +924,160 @@ if {[catch { spi_exec $sql_command }]} { </para> </sect1> - <sect1 id="pltcl-unknown"> - <title>Modules and the <function>unknown</> Command</title> + <sect1 id="pltcl-subtransactions"> + <title>Explicit Subtransactions in PL/Tcl</title> + + <indexterm> + <primary>subtransactions</primary> + <secondary>in PL/Tcl</secondary> + </indexterm> + + <para> + Recovering from errors caused by database access as described in + <xref linkend="pltcl-error-handling"> can lead to an undesirable + situation where some operations succeed before one of them fails, + and after recovering from that error the data is left in an + inconsistent state. PL/Tcl offers a solution to this problem in + the form of explicit subtransactions. + </para> + + <para> + Consider a function that implements a transfer between two accounts: +<programlisting> +CREATE FUNCTION transfer_funds() RETURNS void AS $$ + if [catch { + spi_exec "UPDATE accounts SET balance = balance - 100 WHERE account_name = 'joe'" + spi_exec "UPDATE accounts SET balance = balance + 100 WHERE account_name = 'mary'" + } errormsg] { + set result [format "error transferring funds: %s" $errormsg] + } else { + set result "funds transferred successfully" + } + spi_exec "INSERT INTO operations (result) VALUES ('[quote $result]')" +$$ LANGUAGE pltcl; +</programlisting> + If the second <command>UPDATE</command> statement results in an + exception being raised, this function will log the failure, but + the result of the first <command>UPDATE</command> will + nevertheless be committed. In other words, the funds will be + withdrawn from Joe's account, but will not be transferred to + Mary's account. This happens because each <function>spi_exec</function> + is a separate subtransaction, and only one of those subtransactions + got rolled back. + </para> + + <para> + To handle such cases, you can wrap multiple database operations in an + explicit subtransaction, which will succeed or roll back as a whole. + PL/Tcl provides a <function>subtransaction</function> command to manage + this. We can rewrite our function as: +<programlisting> +CREATE FUNCTION transfer_funds2() RETURNS void AS $$ + if [catch { + subtransaction { + spi_exec "UPDATE accounts SET balance = balance - 100 WHERE account_name = 'joe'" + spi_exec "UPDATE accounts SET balance = balance + 100 WHERE account_name = 'mary'" + } + } errormsg] { + set result [format "error transferring funds: %s" $errormsg] + } else { + set result "funds transferred successfully" + } + spi_exec "INSERT INTO operations (result) VALUES ('[quote $result]')" +$$ LANGUAGE pltcl; +</programlisting> + Note that use of <function>catch</function> is still required for this + purpose. Otherwise the error would propagate to the top level of the + function, preventing the desired insertion into + the <structname>operations</structname> table. + The <function>subtransaction</function> command does not trap errors, it + only assures that all database operations executed inside its scope will + be rolled back together when an error is reported. + </para> + + <para> + A rollback of an explicit subtransaction occurs on any error reported + by the contained Tcl code, not only errors originating from database + access. Thus a regular Tcl exception raised inside + a <function>subtransaction</function> command will also cause the + subtransaction to be rolled back. However, non-error exits out of the + contained Tcl code (for instance, due to <function>return</function>) do + not cause a rollback. + </para> + </sect1> + + <sect1 id="pltcl-config"> + <title>PL/Tcl Configuration</title> + + <para> + This section lists configuration parameters that + affect <application>PL/Tcl</>. + </para> + + <variablelist> + + <varlistentry id="guc-pltcl-start-proc" xreflabel="pltcl.start_proc"> + <term> + <varname>pltcl.start_proc</varname> (<type>string</type>) + <indexterm> + <primary><varname>pltcl.start_proc</> configuration parameter</primary> + </indexterm> + </term> + <listitem> <para> - PL/Tcl has support for autoloading Tcl code when used. - It recognizes a special table, <literal>pltcl_modules</>, which - is presumed to contain modules of Tcl code. If this table - exists, the module <literal>unknown</> is fetched from the table - and loaded into the Tcl interpreter immediately before the first - execution of a PL/Tcl function in a database session. (This - happens separately for each Tcl interpreter, if more than one is - used in a session; see <xref linkend="pltcl-global">.) + This parameter, if set to a nonempty string, specifies the name + (possibly schema-qualified) of a parameterless PL/Tcl function that + is to be executed whenever a new Tcl interpreter is created for + PL/Tcl. Such a function can perform per-session initialization, such + as loading additional Tcl code. A new Tcl interpreter is created + when a PL/Tcl function is first executed in a database session, or + when an additional interpreter has to be created because a PL/Tcl + function is called by a new SQL role. </para> + <para> - While the <literal>unknown</> module could actually contain any - initialization script you need, it normally defines a Tcl - <function>unknown</> procedure that is invoked whenever Tcl does - not recognize an invoked procedure name. <application>PL/Tcl</>'s standard version - of this procedure tries to find a module in <literal>pltcl_modules</> - that will define the required procedure. If one is found, it is - loaded into the interpreter, and then execution is allowed to - proceed with the originally attempted procedure call. A - secondary table <literal>pltcl_modfuncs</> provides an index of - which functions are defined by which modules, so that the lookup - is reasonably quick. + The referenced function must be written in the <literal>pltcl</> + language, and must not be marked <literal>SECURITY DEFINER</>. + (These restrictions ensure that it runs in the interpreter it's + supposed to initialize.) The current user must have permission to + call it, too. </para> + <para> - The <productname>PostgreSQL</productname> distribution includes - support scripts to maintain these tables: - <command>pltcl_loadmod</>, <command>pltcl_listmod</>, - <command>pltcl_delmod</>, as well as source for the standard - <literal>unknown</> module in <filename>share/unknown.pltcl</>. This module - must be loaded - into each database initially to support the autoloading mechanism. + If the function fails with an error it will abort the function call + that caused the new interpreter to be created and propagate out to + the calling query, causing the current transaction or subtransaction + to be aborted. Any actions already done within Tcl won't be undone; + however, that interpreter won't be used again. If the language is + used again the initialization will be attempted again within a fresh + Tcl interpreter. </para> + <para> - The tables <literal>pltcl_modules</> and <literal>pltcl_modfuncs</> - must be readable by all, but it is wise to make them owned and - writable only by the database administrator. As a security - precaution, PL/Tcl will ignore <literal>pltcl_modules</> (and thus, - not attempt to load the <literal>unknown</> module) unless it is - owned by a superuser. But update privileges on this table can be - granted to other users, if you trust them sufficiently. + Only superusers can change this setting. Although this setting + can be changed within a session, such changes will not affect Tcl + interpreters that have already been created. </para> + </listitem> + </varlistentry> + + <varlistentry id="guc-pltclu-start-proc" xreflabel="pltclu.start_proc"> + <term> + <varname>pltclu.start_proc</varname> (<type>string</type>) + <indexterm> + <primary><varname>pltclu.start_proc</> configuration parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter is exactly like <varname>pltcl.start_proc</varname>, + except that it applies to PL/TclU. The referenced function must + be written in the <literal>pltclu</> language. + </para> + </listitem> + </varlistentry> + + </variablelist> </sect1> <sect1 id="pltcl-procnames"> diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml index b31f3731e4..3dfc0f84ed 100644 --- a/doc/src/sgml/postgres-fdw.sgml +++ b/doc/src/sgml/postgres-fdw.sgml @@ -425,6 +425,16 @@ For more detail about the treatment of <literal>CHECK</> constraints on foreign tables, see <xref linkend="sql-createforeigntable">. </para> + + <para> + Tables or foreign tables which are partitions of some other table are + automatically excluded. Partitioned tables are imported, unless they + are a partition of some other table. Since all data can be accessed + through the partitioned table which is the root of the partitioning + hierarchy, this approach should allow access to all the data without + creating extra objects. + </para> + </sect3> </sect2> @@ -532,11 +542,32 @@ <para> <filename>postgres_fdw</> likewise establishes remote session settings - for the parameters <xref linkend="guc-timezone">, - <xref linkend="guc-datestyle">, <xref linkend="guc-intervalstyle">, - and <xref linkend="guc-extra-float-digits">. These are less likely - to be problematic than <varname>search_path</>, but can be handled - with function <literal>SET</> options if the need arises. + for various parameters: + <itemizedlist spacing="compact"> + <listitem> + <para> + <xref linkend="guc-timezone"> is set to <literal>UTC</> + </para> + </listitem> + <listitem> + <para> + <xref linkend="guc-datestyle"> is set to <literal>ISO</> + </para> + </listitem> + <listitem> + <para> + <xref linkend="guc-intervalstyle"> is set to <literal>postgres</> + </para> + </listitem> + <listitem> + <para> + <xref linkend="guc-extra-float-digits"> is set to <literal>3</> for remote + servers 9.0 and newer and is set to <literal>2</> for older versions + </para> + </listitem> + </itemizedlist> + These are less likely to be problematic than <varname>search_path</>, but + can be handled with function <literal>SET</> options if the need arises. </para> <para> diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index be891ff35c..15aa628c16 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -116,6 +116,7 @@ &textsearch; &mvcc; &perform; + ∥ </part> @@ -169,6 +170,7 @@ &monitoring; &diskusage; &wal; + &logical-replication; ®ress; </part> @@ -285,7 +287,6 @@ </part> &biblio; - <![%include-index;[&bookindex;]]> - <![%include-xslt-index;[<index id="bookindex"></index>]]> + <index id="bookindex"></index> </book> diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 9c96d8fc44..4837be5016 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -228,11 +228,11 @@ The server then sends an appropriate authentication request message, to which the frontend must reply with an appropriate authentication response message (such as a password). - For all authentication methods except GSSAPI and SSPI, there is at most - one request and one response. In some methods, no response + For all authentication methods except GSSAPI, SSPI and SASL, there is at + most one request and one response. In some methods, no response at all is needed from the frontend, and so no authentication request - occurs. For GSSAPI and SSPI, multiple exchanges of packets may be needed - to complete the authentication. + occurs. For GSSAPI, SSPI and SASL, multiple exchanges of packets may be + needed to complete the authentication. </para> <para> @@ -330,7 +330,7 @@ <listitem> <para> The frontend must now initiate a GSSAPI negotiation. The frontend - will send a PasswordMessage with the first part of the GSSAPI + will send a GSSResponse message with the first part of the GSSAPI data stream in response to this. If further messages are needed, the server will respond with AuthenticationGSSContinue. </para> @@ -342,7 +342,7 @@ <listitem> <para> The frontend must now initiate a SSPI negotiation. The frontend - will send a PasswordMessage with the first part of the SSPI + will send a GSSResponse with the first part of the SSPI data stream in response to this. If further messages are needed, the server will respond with AuthenticationGSSContinue. </para> @@ -358,7 +358,7 @@ or a previous AuthenticationGSSContinue). If the GSSAPI or SSPI data in this message indicates more data is needed to complete the authentication, - the frontend must send that data as another PasswordMessage. If + the frontend must send that data as another GSSResponse message. If GSSAPI or SSPI authentication is completed by this message, the server will next send AuthenticationOk to indicate successful authentication or ErrorResponse to indicate failure. @@ -366,6 +366,46 @@ </listitem> </varlistentry> + <varlistentry> + <term>AuthenticationSASL</term> + <listitem> + <para> + The frontend must now initiate a SASL negotiation, using one of the + SASL mechanisms listed in the message. The frontend will send a + SASLInitialResponse with the name of the selected mechanism, and the + first part of the SASL data stream in response to this. If further + messages are needed, the server will respond with + AuthenticationSASLContinue. See <xref linkend="sasl-authentication"> + for details. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>AuthenticationSASLContinue</term> + <listitem> + <para> + This message contains challenge data from the previous step of SASL + negotiation (AuthenticationSASL, or a previous + AuthenticationSASLContinue). The frontend must respond with a + SASLResponse message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>AuthenticationSASLFinal</term> + <listitem> + <para> + SASL authentication has completed with additional mechanism-specific + data for the client. The server will next send AuthenticationOk to + indicate successful authentication, or an ErrorResponse to indicate + failure. This message is sent only if the SASL mechanism specifies + additional data to be sent from server to client at completion. + </para> + </listitem> + </varlistentry> + </variablelist> </para> @@ -668,7 +708,7 @@ number of parameter symbols (<literal>$</><replaceable>n</>) used in the query string. Another special case is that a parameter's type can be specified as <type>void</> (that is, the OID of the - <type>void</> pseudotype). This is meant to allow parameter symbols + <type>void</> pseudo-type). This is meant to allow parameter symbols to be used for function parameters that are actually OUT parameters. Ordinarily there is no context in which a <type>void</> parameter could be used, but if such a parameter symbol appears in a function's @@ -1297,6 +1337,141 @@ </sect2> </sect1> +<sect1 id="sasl-authentication"> +<title>SASL Authentication</title> + +<para> +<firstterm>SASL</> is a framework for authentication in connection-oriented +protocols. At the moment, <productname>PostgreSQL</> implements only one SASL +authentication mechanism, SCRAM-SHA-256, but more might be added in the +future. The below steps illustrate how SASL authentication is performed in +general, while the next subsection gives more details on SCRAM-SHA-256. +</para> + +<procedure> +<title>SASL Authentication Message Flow</title> + +<step id="sasl-auth-begin"> +<para> + To begin a SASL authentication exchange, the server sends an + AuthenticationSASL message. It includes a list of SASL authentication + mechanisms that the server can accept, in the server's preferred order. +</para> +</step> + +<step id="sasl-auth-initial-response"> +<para> + The client selects one of the supported mechanisms from the list, and sends + a SASLInitialResponse message to the server. The message includes the name + of the selected mechanism, and an optional Initial Client Response, if the + selected mechanism uses that. +</para> +</step> + +<step id="sasl-auth-continue"> +<para> + One or more server-challenge and client-response message will follow. Each + server-challenge is sent in an AuthenticationSASLContinue message, followed + by a response from client in an SASLResponse message. The particulars of + the messages are mechanism specific. +</para> +</step> + +<step id="sasl-auth-end"> +<para> + Finally, when the authentication exchange is completed successfully, the + server sends an AuthenticationSASLFinal message, followed + immediately by an AuthenticationOk message. The AuthenticationSASLFinal + contains additional server-to-client data, whose content is particular to the + selected authentication mechanism. If the authentication mechanism doesn't + use additional data that's sent at completion, the AuthenticationSASLFinal + message is not sent. +</para> +</step> +</procedure> + +<para> +On error, the server can abort the authentication at any stage, and send an +ErrorMessage. +</para> + + <sect2 id="sasl-scram-sha256"> + <title>SCRAM-SHA-256 authentication</title> + + <para> + <firstterm>SCRAM-SHA-256</> (called just <firstterm>SCRAM</> from now on) is + the only implemented SASL mechanism, at the moment. It is described in detail + in RFC 7677 and RFC 5802. + </para> + + <para> +When SCRAM-SHA-256 is used in PostgreSQL, the server will ignore the username +that the client sends in the <structname>client-first-message</>. The username +that was already sent in the startup message is used instead. +<productname>PostgreSQL</> supports multiple character encodings, while SCRAM +dictates UTF-8 to be used for the username, so it might be impossible to +represent the PostgreSQL username in UTF-8. To avoid confusion, the client +should use <literal>pg_same_as_startup_message</literal> as the username in the +<structname>client-first-message</>. + </para> + + <para> +The SCRAM specification dictates that the password is also in UTF-8, and is +processed with the <firstterm>SASLprep</> algorithm. +<productname>PostgreSQL</>, however, does not require UTF-8 to be used for +the password. When a user's password is set, it is processed with SASLprep +as if it was in UTF-8, regardless of the actual encoding used. However, if +it is not a legal UTF-8 byte sequence, or it contains UTF-8 byte sequences +that are prohibited by the SASLprep algorithm, the raw password will be used +without SASLprep processing, instead of throwing an error. This allows the +password to be normalized when it is in UTF-8, but still allows a non-UTF-8 +password to be used, and doesn't require the system to know which encoding +the password is in. + </para> + + <para> +<firstterm>Channel binding</> has not been implemented yet. + </para> + +<procedure> +<title>Example</title> + <step id="scram-begin"> +<para> + The server sends an AuthenticationSASL message. It includes a list of + SASL authentication mechanisms that the server can accept. +</para> +</step> +<step id="scram-client-first"> +<para> + The client responds by sending a SASLInitialResponse message, which + indicates the chosen mechanism, <literal>SCRAM-SHA-256</>. In the Initial + Client response field, the message contains the SCRAM + <structname>client-first-message</>. +</para> +</step> +<step id="scram-server-first"> +<para> + Server sends an AuthenticationSASLContinue message, with a SCRAM + <structname>server-first message</> as the content. +</para> +</step> +<step id="scram-client-final"> +<para> + Client sends a SASLResponse message, with SCRAM + <structname>client-final-message</> as the content. +</para> +</step> +<step id="scram-server-final"> +<para> + Server sends an AuthenticationSASLFinal message, with the SCRAM + <structname>server-final-message</>, followed immediately by + an AuthenticationOk message. +</para> +</step> +</procedure> +</sect2> +</sect1> + <sect1 id="protocol-replication"> <title>Streaming Replication Protocol</title> @@ -1321,7 +1496,7 @@ the connection to be used for logical replication from that database. psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" </programlisting> However, it is often more useful to use - <xref linkend="app-pgreceivexlog"> (for physical replication) or + <xref linkend="app-pgreceivewal"> (for physical replication) or <xref linkend="app-pgrecvlogical"> (for logical replication). </para> @@ -1371,8 +1546,8 @@ The commands accepted in walsender mode are: </term> <listitem> <para> - Current xlog flush location. Useful to get a known location in the - transaction log where streaming can start. + Current WAL flush location. Useful to get a known location in the + write-ahead log where streaming can start. </para> </listitem> </varlistentry> @@ -1394,6 +1569,30 @@ The commands accepted in walsender mode are: </varlistentry> <varlistentry> + <term><literal>SHOW</literal> <replaceable class="parameter">name</replaceable> + <indexterm><primary>SHOW</primary></indexterm> + </term> + <listitem> + <para> + Requests the server to send the current setting of a run-time parameter. + This is similar to the SQL command <xref linkend="sql-show">. + </para> + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">name</></term> + <listitem> + <para> + The name of a run-time parameter. Available parameters are documented + in <xref linkend="runtime-config">. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> <term><literal>TIMELINE_HISTORY</literal> <replaceable class="parameter">tli</replaceable> <indexterm><primary>TIMELINE_HISTORY</primary></indexterm> </term> @@ -1433,8 +1632,8 @@ The commands accepted in walsender mode are: </listitem> </varlistentry> - <varlistentry> - <term><literal>CREATE_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</> { <literal>PHYSICAL</> [ <literal>RESERVE_WAL</> ] | <literal>LOGICAL</> <replaceable class="parameter">output_plugin</> } + <varlistentry id="protocol-replication-create-slot" xreflabel="CREATE_REPLICATION_SLOT"> + <term><literal>CREATE_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</> [ <literal>TEMPORARY</> ] { <literal>PHYSICAL</> [ <literal>RESERVE_WAL</> ] | <literal>LOGICAL</> <replaceable class="parameter">output_plugin</> [ <literal>EXPORT_SNAPSHOT</> | <literal>NOEXPORT_SNAPSHOT</> | <literal>USE_SNAPSHOT</> ] } <indexterm><primary>CREATE_REPLICATION_SLOT</primary></indexterm> </term> <listitem> @@ -1465,6 +1664,17 @@ The commands accepted in walsender mode are: </varlistentry> <varlistentry> + <term><literal>TEMPORARY</></term> + <listitem> + <para> + Specify that this replication slot is a temporary one. Temporary + slots are not saved to disk and are automatically dropped on error + or when the session has finished. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><literal>RESERVE_WAL</></term> <listitem> <para> @@ -1474,7 +1684,76 @@ The commands accepted in walsender mode are: </para> </listitem> </varlistentry> + + <varlistentry> + <term><literal>EXPORT_SNAPSHOT</></term> + <term><literal>NOEXPORT_SNAPSHOT</></term> + <term><literal>USE_SNAPSHOT</></term> + <listitem> + <para> + Decides what to do with the snapshot created during logical slot + initialization. <literal>EXPORT_SNAPSHOT</>, which is the default, + will export the snapshot for use in other sessions. This option can't + be used inside a transaction. <literal>USE_SNAPSHOT</> will use the + snapshot for the current transaction executing the command. This + option must be used in a transaction, and + <literal>CREATE_REPLICATION_SLOT</literal> must be the first command + run in that transaction. Finally, <literal>NOEXPORT_SNAPSHOT</> will + just use the snapshot for logical decoding as normal but won't do + anything else with it. + </para> + </listitem> + </varlistentry> </variablelist> + + <para> + In response to this command, the server will send a one-row result set + containing the following fields: + + <variablelist> + <varlistentry> + <term><literal>slot_name</literal> (<type>text</type>)</term> + <listitem> + <para> + The name of the newly-created replication slot. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>consistent_point</literal> (<type>text</type>)</term> + <listitem> + <para> + The WAL location at which the slot became consistent. This is the + earliest location from which streaming can start on this replication + slot. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>snapshot_name</literal> (<type>text</type>)</term> + <listitem> + <para> + The identifier of the snapshot exported by the command. The + snapshot is valid until a new command is executed on this connection + or the replication connection is closed. Null if the created slot + is physical. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>output_plugin</literal> (<type>text</type>)</term> + <listitem> + <para> + The name of the output plugin used by the newly-created replication + slot. Null if the created slot is physical. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> </listitem> </varlistentry> @@ -1485,7 +1764,7 @@ The commands accepted in walsender mode are: <listitem> <para> Instructs server to start streaming WAL, starting at - WAL position <replaceable class="parameter">XXX/XXX</>. + WAL location <replaceable class="parameter">XXX/XXX</>. If <literal>TIMELINE</literal> option is specified, streaming starts on timeline <replaceable class="parameter">tli</>; otherwise, the server's current timeline is selected. The server can @@ -1517,7 +1796,7 @@ The commands accepted in walsender mode are: acknowledges this by also exiting COPY mode, the server sends a result set with one row and two columns, indicating the next timeline in this server's history. The first column is the next timeline's ID (type <type>int8</type>), and the - second column is the WAL position where the switch happened (type <type>text</type>). Usually, + second column is the WAL location where the switch happened (type <type>text</type>). Usually, the switch position is the end of the WAL that was streamed, but there are corner cases where the server can send some WAL from the old timeline that it has not itself replayed before promoting. Finally, the @@ -1783,10 +2062,33 @@ The commands accepted in walsender mode are: </term> <listitem> <para> - The standby's current xmin. This may be 0, if the standby is - sending notification that Hot Standby feedback will no longer - be sent on this connection. Later non-zero messages may - reinitiate the feedback mechanism. + The standby's current global xmin, excluding the catalog_xmin from any + replication slots. If both this value and the following + catalog_xmin are 0 this is treated as a notification that Hot Standby + feedback will no longer be sent on this connection. Later non-zero + messages may reinitiate the feedback mechanism. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Int32 + </term> + <listitem> + <para> + The epoch of the global xmin xid on the standby. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Int32 + </term> + <listitem> + <para> + The lowest catalog_xmin of any replication slots on the standby. Set to 0 + if no catalog_xmin exists on the standby or if hot standby feedback is being + disabled. </para> </listitem> </varlistentry> @@ -1796,7 +2098,7 @@ The commands accepted in walsender mode are: </term> <listitem> <para> - The standby's current epoch. + The epoch of the catalog_xmin xid on the standby. </para> </listitem> </varlistentry> @@ -1813,7 +2115,7 @@ The commands accepted in walsender mode are: <listitem> <para> Instructs server to start streaming WAL for logical replication, starting - at WAL position <replaceable class="parameter">XXX/XXX</>. The server can + at WAL location <replaceable class="parameter">XXX/XXX</>. The server can reply with an error, for example if the requested section of WAL has already been recycled. On success, server responds with a CopyBothResponse message, and then starts to stream WAL to the frontend. @@ -1845,7 +2147,7 @@ The commands accepted in walsender mode are: <term><replaceable class="parameter">XXX/XXX</></term> <listitem> <para> - The WAL position to begin streaming at. + The WAL location to begin streaming at. </para> </listitem> </varlistentry> @@ -1878,6 +2180,8 @@ The commands accepted in walsender mode are: <para> Drops a replication slot, freeing any reserved server-side resources. If the slot is currently in use by an active connection, this command fails. + If the slot is a logical slot that was created in a database other than + the database the walsender is connected to, this command fails. </para> <variablelist> <varlistentry> @@ -1947,7 +2251,7 @@ The commands accepted in walsender mode are: <para> Include the necessary WAL segments in the backup. This will include all the files between start and stop backup in the - <filename>pg_xlog</filename> directory of the base directory tar + <filename>pg_wal</filename> directory of the base directory tar file. </para> </listitem> @@ -2069,26 +2373,33 @@ The commands accepted in walsender mode are: </listitem> <listitem> <para> - various temporary files created during the operation of the PostgreSQL server + Various temporary files and directories created during the operation + of the PostgreSQL server, such as any file or directory beginning + with <filename>pgsql_tmp</>. </para> </listitem> <listitem> <para> - <filename>pg_xlog</>, including subdirectories. If the backup is run - with WAL files included, a synthesized version of <filename>pg_xlog</filename> will be + <filename>pg_wal</>, including subdirectories. If the backup is run + with WAL files included, a synthesized version of <filename>pg_wal</filename> will be included, but it will only contain the files necessary for the backup to work, not the rest of the contents. </para> </listitem> <listitem> <para> - <filename>pg_replslot</> is copied as an empty directory. + <filename>pg_dynshmem</>, <filename>pg_notify</>, + <filename>pg_replslot</>, <filename>pg_serial</>, + <filename>pg_snapshots</>, <filename>pg_stat_tmp</>, and + <filename>pg_subtrans</> are copied as empty directories (even if + they are symbolic links). </para> </listitem> <listitem> <para> Files other than regular files and directories, such as symbolic - links and special device files, are skipped. (Symbolic links + links (other than for the directories listed above) and special + device files, are skipped. (Symbolic links in <filename>pg_tblspc</filename> are maintained.) </para> </listitem> @@ -2104,6 +2415,119 @@ The commands accepted in walsender mode are: </sect1> +<sect1 id="protocol-logical-replication"> + <title>Logical Streaming Replication Protocol</title> + + <para> + This section describes the logical replication protocol, which is the message + flow started by the <literal>START_REPLICATION</literal> + <literal>SLOT</literal> <replaceable class="parameter">slot_name</> + <literal>LOGICAL</literal> replication command. + </para> + + <para> + The logical streaming replication protocol builds on the primitives of + the physical streaming replication protocol. + </para> + + <sect2 id="protocol-logical-replication-params"> + <title>Logical Streaming Replication Parameters</title> + + <para> + The logical replication <literal>START_REPLICATION</literal> command + accepts following parameters: + + <variablelist> + <varlistentry> + <term> + proto_version + </term> + <listitem> + <para> + Protocol version. Currently only version <literal>1</literal> is + supported. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + publication_names + </term> + <listitem> + <para> + Comma separated list of publication names for which to subscribe + (receive changes). The individual publication names are treated + as standard objects names and can be quoted the same as needed. + </para> + </listitem> + </varlistentry> + </variablelist> + + </para> + </sect2> + + <sect2 id="protocol-logical-messages"> + <title>Logical Replication Protocol Messages</title> + + <para> + The individual protocol messages are discussed in the following + subsections. Individual messages are described in + <xref linkend="protocol-logicalrep-message-formats">. + </para> + + <para> + All top-level protocol messages begin with a message type byte. + While represented in code as a character, this is a signed byte with no + associated encoding. + </para> + + <para> + Since the streaming replication protocol supplies a message length there + is no need for top-level protocol messages to embed a length in their + header. + </para> + + </sect2> + + <sect2 id="protocol-logical-messages-flow"> + <title>Logical Replication Protocol Message Flow</title> + + <para> + With the exception of the <literal>START_REPLICATION</literal> command and + the replay progress messages, all information flows only from the backend + to the frontend. + </para> + + <para> + The logical replication protocol sends individual transactions one by one. + This means that all messages between a pair of Begin and Commit messages + belong to the same transaction. + </para> + + <para> + Every sent transaction contains zero or more DML messages (Insert, + Update, Delete). In case of a cascaded setup it can also contain Origin + messages. The origin message indicated that the transaction originated on + different replication node. Since a replication node in the scope of logical + replication protocol can be pretty much anything, the only identifier + is the origin name. It's downstream's responsibility to handle this as + needed (if needed). The Origin message is always sent before any DML + messages in the transaction. + </para> + + <para> + Every DML message contains an arbitrary relation ID, which can be mapped to + an ID in the Relation messages. The Relation messages describe the schema of the + given relation. The Relation message is sent for a given relation either + because it is the first time we send a DML message for given relation in the + current session or because the relation definition has changed since the + last Relation message was sent for it. The protocol assumes that the client + is capable of caching the metadata for as many relations as needed. + </para> + </sect2> +</sect1> + <sect1 id="protocol-message-types"> <title>Message Data Types</title> @@ -2524,6 +2948,8 @@ AuthenticationSSPI (B) </para> </listitem> </varlistentry> + + <varlistentry> <term> AuthenticationGSSContinue (B) @@ -2581,6 +3007,178 @@ AuthenticationGSSContinue (B) <varlistentry> <term> +AuthenticationSASL (B) +</term> +<listitem> +<para> + +<variablelist> +<varlistentry> +<term> + Byte1('R') +</term> +<listitem> +<para> + Identifies the message as an authentication request. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int32 +</term> +<listitem> +<para> + Length of message contents in bytes, including self. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int32(10) +</term> +<listitem> +<para> + Specifies that SASL authentication is required. +</para> +</listitem> +</varlistentry> +</variablelist> +The message body is a list of SASL authentication mechanisms, in the +server's order of preference. A zero byte is required as terminator after +the last authentication mechanism name. For each mechanism, there is the +following: +<variablelist> +<varlistentry> +<term> + String +</term> +<listitem> +<para> + Name of a SASL authentication mechanism. +</para> +</listitem> +</varlistentry> +</variablelist> + +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term> +AuthenticationSASLContinue (B) +</term> +<listitem> +<para> + +<variablelist> +<varlistentry> +<term> + Byte1('R') +</term> +<listitem> +<para> + Identifies the message as an authentication request. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int32 +</term> +<listitem> +<para> + Length of message contents in bytes, including self. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int32(11) +</term> +<listitem> +<para> + Specifies that this message contains a SASL challenge. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Byte<replaceable>n</replaceable> +</term> +<listitem> +<para> + SASL data, specific to the SASL mechanism being used. +</para> +</listitem> +</varlistentry> +</variablelist> + +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term> +AuthenticationSASLFinal (B) +</term> +<listitem> +<para> + +<variablelist> +<varlistentry> +<term> + Byte1('R') +</term> +<listitem> +<para> + Identifies the message as an authentication request. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int32 +</term> +<listitem> +<para> + Length of message contents in bytes, including self. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int32(12) +</term> +<listitem> +<para> + Specifies that SASL authentication has completed. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Byte<replaceable>n</replaceable> +</term> +<listitem> +<para> + SASL outcome "additional data", specific to the SASL mechanism + being used. +</para> +</listitem> +</varlistentry> +</variablelist> + +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term> BackendKeyData (B) </term> <listitem> @@ -3930,6 +4528,52 @@ FunctionCallResponse (B) <varlistentry> <term> +GSSResponse (F) +</term> +<listitem> +<para> + +<variablelist> +<varlistentry> +<term> + Byte1('p') +</term> +<listitem> +<para> + Identifies the message as a GSSAPI or SSPI response. Note that + this is also used for SASL and password response messages. + The exact message type can be deduced from the context. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int32 +</term> +<listitem> +<para> + Length of message contents in bytes, including self. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Byte<replaceable>n</replaceable> +</term> +<listitem> +<para> + GSSAPI/SSPI specific message data. +</para> +</listitem> +</varlistentry> +</variablelist> +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term> NoData (B) </term> <listitem> @@ -4340,10 +4984,8 @@ PasswordMessage (F) <listitem> <para> Identifies the message as a password response. Note that - this is also used for GSSAPI and SSPI response messages - (which is really a design error, since the contained data - is not a null-terminated string in that case, but can be - arbitrary binary data). + this is also used for GSSAPI, SSPI and SASL response messages. + The exact message type can be deduced from the context. </para> </listitem> </varlistentry> @@ -4632,6 +5274,120 @@ RowDescription (B) <varlistentry> <term> +SASLInitialresponse (F) +</term> +<listitem> +<para> + +<variablelist> +<varlistentry> +<term> + Byte1('p') +</term> +<listitem> +<para> + Identifies the message as an initial SASL response. Note that + this is also used for GSSAPI, SSPI and password response messages. + The exact message type is deduced from the context. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int32 +</term> +<listitem> +<para> + Length of message contents in bytes, including self. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + String +</term> +<listitem> +<para> + Name of the SASL authentication mechanism that the client + selected. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int32 +</term> +<listitem> +<para> + Length of SASL mechanism specific "Initial Client Response" that + follows, or -1 if there is no Initial Response. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Byte<replaceable>n</replaceable> +</term> +<listitem> +<para> + SASL mechanism specific "Initial Response". +</para> +</listitem> +</varlistentry> +</variablelist> +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term> +SASLResponse (F) +</term> +<listitem> +<para> + +<variablelist> +<varlistentry> +<term> + Byte1('p') +</term> +<listitem> +<para> + Identifies the message as a SASL response. Note that + this is also used for GSSAPI, SSPI and password response messages. + The exact message type can be deduced from the context. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int32 +</term> +<listitem> +<para> + Length of message contents in bytes, including self. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Byte<replaceable>n</replaceable> +</term> +<listitem> +<para> + SASL mechanism specific message data. +</para> +</listitem> +</varlistentry> +</variablelist> +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term> SSLRequest (F) </term> <listitem> @@ -4752,6 +5508,22 @@ StartupMessage (F) </para> </listitem> </varlistentry> +<varlistentry> +<term> + <literal>replication</> +</term> +<listitem> +<para> + Used to connect in streaming replication mode, where + a small set of replication commands can be issued + instead of SQL statements. Value can be + <literal>true</>, <literal>false</>, or + <literal>database</>, and the default is + <literal>false</>. See + <xref linkend="protocol-replication"> for details. +</para> +</listitem> +</varlistentry> </variablelist> In addition to the above, any run-time parameter that can be @@ -4884,6 +5656,25 @@ message. <varlistentry> <term> +<literal>V</> +</term> +<listitem> +<para> + Severity: the field contents are + <literal>ERROR</>, <literal>FATAL</>, or + <literal>PANIC</> (in an error message), or + <literal>WARNING</>, <literal>NOTICE</>, <literal>DEBUG</>, + <literal>INFO</>, or <literal>LOG</> (in a notice message). + This is identical to the <literal>S</> field except + that the contents are never localized. This is present only in + messages generated by <productname>PostgreSQL</> versions 9.6 + and later. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> <literal>C</> </term> <listitem> @@ -5112,6 +5903,617 @@ not line breaks. </sect1> +<sect1 id="protocol-logicalrep-message-formats"> +<title>Logical Replication Message Formats</title> + +<para> +This section describes the detailed format of each logical replication message. +These messages are returned either by the replication slot SQL interface or are +sent by a walsender. In case of a walsender they are encapsulated inside the replication +protocol WAL messages as described in <xref linkend="protocol-replication"> +and generally obey same message flow as physical replication. +</para> + +<variablelist> + +<varlistentry> +<term> +Begin +</term> +<listitem> +<para> + +<variablelist> +<varlistentry> +<term> + Byte1('B') +</term> +<listitem> +<para> + Identifies the message as a begin message. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int64 +</term> +<listitem> +<para> + The final LSN of the transaction. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int64 +</term> +<listitem> +<para> + Commit timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int32 +</term> +<listitem> +<para> + Xid of the transaction. +</para> +</listitem> +</varlistentry> + +</variablelist> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +Commit +</term> +<listitem> +<para> + +<variablelist> +<varlistentry> +<term> + Byte1('C') +</term> +<listitem> +<para> + Identifies the message as a commit message. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int64 +</term> +<listitem> +<para> + The LSN of the commit. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int64 +</term> +<listitem> +<para> + The end LSN of the transaction. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int64 +</term> +<listitem> +<para> + Commit timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). +</para> +</listitem> +</varlistentry> + +</variablelist> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +Origin +</term> +<listitem> +<para> + +<variablelist> +<varlistentry> +<term> + Byte1('O') +</term> +<listitem> +<para> + Identifies the message as an origin message. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int64 +</term> +<listitem> +<para> + The LSN of the commit on the origin server. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + String +</term> +<listitem> +<para> + Name of the origin. +</para> +</listitem> +</varlistentry> + +</variablelist> +</para> + +<para> + Note that there can be multiple Origin messages inside a single transaction. +</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term> +Relation +</term> +<listitem> +<para> + +<variablelist> +<varlistentry> +<term> + Byte1('R') +</term> +<listitem> +<para> + Identifies the message as a relation message. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int32 +</term> +<listitem> +<para> + ID of the relation. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + String +</term> +<listitem> +<para> + Namespace (empty string for <literal>pg_catalog</literal>). +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + String +</term> +<listitem> +<para> + Relation name. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> + Int8 +</term> +<listitem> +<para> + Replica identity setting for the relation (same as + <structfield>relreplident</structfield> in <structname>pg_class</structname>). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> + Int16 +</term> +<listitem> +<para> + Number of columns. +</para> +</listitem> +</varlistentry> +</variablelist> + Next, the following message part appears for each column: +<variablelist> +<varlistentry> +<term> + Int8 +</term> +<listitem> +<para> + Flags for the column. Currently can be either 0 for no flags + or 1 which marks the column as part of the key. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + String +</term> +<listitem> +<para> + Name of the column. +</para> +</listitem> +</varlistentry> + +</variablelist> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +Insert +</term> +<listitem> +<para> + +<variablelist> +<varlistentry> +<term> + Byte1('I') +</term> +<listitem> +<para> + Identifies the message as an insert message. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int32 +</term> +<listitem> +<para> + ID of the relation corresponding to the ID in the relation + message. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Byte1('N') +</term> +<listitem> +<para> + Identifies the following TupleData message as a new tuple. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> + TupleData +</term> +<listitem> +<para> + TupleData message part representing the contents of new tuple. +</para> +</listitem> +</varlistentry> + +</variablelist> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +Update +</term> +<listitem> +<para> + +<variablelist> +<varlistentry> +<term> + Byte1('U') +</term> +<listitem> +<para> + Identifies the message as an update message. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int32 +</term> +<listitem> +<para> + ID of the relation corresponding to the ID in the relation + message. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> + Byte1('K') +</term> +<listitem> +<para> + Identifies the following TupleData submessage as a key. + This field is optional and is only present if + the update changed data in any of the column(s) that are + part of the REPLICA IDENTITY index. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> + Byte1('O') +</term> +<listitem> +<para> + Identifies the following TupleData submessage as an old tuple. + This field is optional and is only present if table in which + the update happened has REPLICA IDENTITY set to FULL. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> + TupleData +</term> +<listitem> +<para> + TupleData message part representing the contents of the old tuple + or primary key. Only present if the previous 'O' or 'K' part + is present. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> + Byte1('N') +</term> +<listitem> +<para> + Identifies the following TupleData message as a new tuple. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> + TupleData +</term> +<listitem> +<para> + TupleData message part representing the contents of a new tuple. +</para> +</listitem> +</varlistentry> + +</variablelist> +</para> + +<para> + The Update message may contain either a 'K' message part or an 'O' message part + or neither of them, but never both of them. +</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term> +Delete +</term> +<listitem> +<para> + +<variablelist> +<varlistentry> +<term> + Byte1('D') +</term> +<listitem> +<para> + Identifies the message as a delete message. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int32 +</term> +<listitem> +<para> + ID of the relation corresponding to the ID in the relation + message. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> + Byte1('K') +</term> +<listitem> +<para> + Identifies the following TupleData submessage as a key. + This field is present if the table in which the delete has + happened uses an index as REPLICA IDENTITY. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> + Byte1('O') +</term> +<listitem> +<para> + Identifies the following TupleData message as a old tuple. + This field is is present if the table in which the delete has + happened has REPLICA IDENTITY set to FULL. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> + TupleData +</term> +<listitem> +<para> + TupleData message part representing the contents of the old tuple + or primary key, depending on the previous field. +</para> +</listitem> +</varlistentry> +</variablelist> +</para> + +<para> + The Delete message may contain either a 'K' message part or an 'O' message part, + but never both of them. +</para> + +</listitem> +</varlistentry> + +</variablelist> + +<para> + +Following message parts that are shared by above messages. + +</para> + +<variablelist> + +<varlistentry> +<term> +TupleData +</term> +<listitem> +<para> + +<variablelist> +<varlistentry> +<term> + Int16 +</term> +<listitem> +<para> + Number of columns. +</para> +</listitem> +</varlistentry> +</variablelist> + Next, one of the following submessages appears for each column: +<variablelist> +<varlistentry> +<term> + Byte1('n') +</term> +<listitem> +<para> + Identifies the data as NULL value. +</para> +</listitem> +</varlistentry> +</variablelist> + Or +<variablelist> +<varlistentry> +<term> + Byte1('u') +</term> +<listitem> +<para> + Identifies unchanged TOASTed value (the actual value is not + sent). +</para> +</listitem> +</varlistentry> +</variablelist> + Or +<variablelist> +<varlistentry> +<term> + Byte1('t') +</term> +<listitem> +<para> + Identifies the data as text formatted value. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Int32 +</term> +<listitem> +<para> + Length of the column value. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> + Byte<replaceable>n</replaceable> +</term> +<listitem> +<para> + The value of the column, in text format. (A future release + might support additional formats.) + <replaceable>n</replaceable> is the above length. + +</para> +</listitem> +</varlistentry> + +</variablelist> +</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + <sect1 id="protocol-changes"> <title>Summary of Changes since Protocol 2.0</title> diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml index 718262f1aa..30792f45f1 100644 --- a/doc/src/sgml/queries.sgml +++ b/doc/src/sgml/queries.sgml @@ -145,11 +145,9 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r <para> Instead of writing <literal>ONLY</> before the table name, you can write <literal>*</> after the table name to explicitly specify that descendant - tables are included. Writing <literal>*</> is not necessary since that - behavior is the default (unless you have changed the setting of the <xref - linkend="guc-sql-inheritance"> configuration option). However writing - <literal>*</> might be useful to emphasize that additional tables will be - searched. + tables are included. There is no real reason to use this syntax any more, + because searching descendant tables is now always the default behavior. + However, it is supported for compatibility with older releases. </para> <sect3 id="queries-join"> @@ -764,7 +762,7 @@ SELECT * FROM vw_getfoo; In some cases it is useful to define table functions that can return different column sets depending on how they are invoked. To support this, the table function can be declared as returning - the pseudotype <type>record</>. When such a function is used in + the pseudo-type <type>record</>. When such a function is used in a query, the expected row structure must be specified in the query itself, so that the system can know how to parse and plan the query. This syntax looks like: @@ -1457,7 +1455,8 @@ SELECT tbl1.a, tbl2.a, tbl1.b FROM ... <programlisting> SELECT tbl1.*, tbl2.a FROM ... </programlisting> - (See also <xref linkend="queries-where">.) + See <xref linkend="rowtypes-usage"> for more about + the <replaceable>table_name</><literal>.*</> notation. </para> <para> @@ -2262,7 +2261,8 @@ SELECT * FROM moved_rows; <para> Data-modifying statements in <literal>WITH</> usually have - <literal>RETURNING</> clauses, as seen in the example above. + <literal>RETURNING</> clauses (see <xref linkend="dml-returning">), + as shown in the example above. It is the output of the <literal>RETURNING</> clause, <emphasis>not</> the target table of the data-modifying statement, that forms the temporary table that can be referred to by the rest of the query. If a diff --git a/doc/src/sgml/query.sgml b/doc/src/sgml/query.sgml index f4fbf11a8d..98434925df 100644 --- a/doc/src/sgml/query.sgml +++ b/doc/src/sgml/query.sgml @@ -754,7 +754,7 @@ SELECT city, max(temp_lo) <programlisting> SELECT city, max(temp_lo) FROM weather - WHERE city LIKE 'S%'<co id="co.tutorial-agg-like"> + WHERE city LIKE 'S%' -- <co id="co.tutorial-agg-like"> GROUP BY city HAVING max(temp_lo) < 40; </programlisting> diff --git a/doc/src/sgml/recovery-config.sgml b/doc/src/sgml/recovery-config.sgml index e04a157cc5..4797156edd 100644 --- a/doc/src/sgml/recovery-config.sgml +++ b/doc/src/sgml/recovery-config.sgml @@ -157,7 +157,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows By default, recovery will recover to the end of the WAL log. The following parameters can be used to specify an earlier stopping point. At most one of <varname>recovery_target</>, - <varname>recovery_target_name</>, <varname>recovery_target_time</>, + <varname>recovery_target_lsn</>, <varname>recovery_target_name</>, <varname>recovery_target_time</>, <varname>recovery_target_xid</> or <varname>recovery_target_barrier</> can be used; if more than one of these is specified in the configuration file, the last entry will be used. </para> @@ -246,6 +246,21 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows one of <varname>recovery_target_xid</>, <xref linkend="recovery-target-time"> and <varname>recovery_target_barrier</> can be specified. + </varlistentry> + + <varlistentry id="recovery-target-lsn" xreflabel="recovery_target_lsn"> + <term><varname>recovery_target_lsn</varname> (<type>pg_lsn</type>) + <indexterm> + <primary><varname>recovery_target_lsn</> recovery parameter</primary> + </indexterm> + </term> + <listitem> + <para> + This parameter specifies the LSN of the write-ahead log location up + to which recovery will proceed. The precise stopping point is also + influenced by <xref linkend="recovery-target-inclusive">. This + parameter is parsed using the system data type + <link linkend="datatype-pg-lsn"><type>pg_lsn</></link>. </para> </listitem> </varlistentry> @@ -320,7 +335,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows to be executed against the database to check if this recovery target is the most desirable point for recovery. The paused state can be resumed by - using <function>pg_xlog_replay_resume()</> (see + using <function>pg_wal_replay_resume()</> (see <xref linkend="functions-recovery-control-table">), which then causes recovery to end. If this recovery target is not the desired stopping point, then shut down the server, change the @@ -486,10 +501,17 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows <para> This parameter is intended for use with streaming replication deployments; however, if the parameter is specified it will be honored in all cases. - Synchronous replication is not affected by this setting because there is - not yet any setting to request synchronous apply of transaction commits. + <varname>hot_standby_feedback</> will be delayed by use of this feature which could lead to bloat on the master; use both together with care. + + <warning> + <para> + Synchronous replication is affected by this setting when <varname>synchronous_commit</varname> + is set to <literal>remote_apply</literal>; every <literal>COMMIT</literal> + will need to wait to be applied. + </para> + </warning> </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index 0c5e3b350e..3ef0b5af79 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -27,12 +27,15 @@ Complete list of usable sgml source files in this directory. <!ENTITY alterOperatorClass SYSTEM "alter_opclass.sgml"> <!ENTITY alterOperatorFamily SYSTEM "alter_opfamily.sgml"> <!ENTITY alterPolicy SYSTEM "alter_policy.sgml"> +<!ENTITY alterPublication SYSTEM "alter_publication.sgml"> <!ENTITY alterRole SYSTEM "alter_role.sgml"> <!ENTITY alterRule SYSTEM "alter_rule.sgml"> <!ENTITY alterSchema SYSTEM "alter_schema.sgml"> <!ENTITY alterServer SYSTEM "alter_server.sgml"> <!ENTITY alterSequence SYSTEM "alter_sequence.sgml"> +<!ENTITY alterSubscription SYSTEM "alter_subscription.sgml"> <!ENTITY alterSystem SYSTEM "alter_system.sgml"> +<!ENTITY alterStatistics SYSTEM "alter_statistics.sgml"> <!ENTITY alterTable SYSTEM "alter_table.sgml"> <!ENTITY alterTableSpace SYSTEM "alter_tablespace.sgml"> <!ENTITY alterTSConfig SYSTEM "alter_tsconfig.sgml"> @@ -77,11 +80,14 @@ Complete list of usable sgml source files in this directory. <!ENTITY createOperatorClass SYSTEM "create_opclass.sgml"> <!ENTITY createOperatorFamily SYSTEM "create_opfamily.sgml"> <!ENTITY createPolicy SYSTEM "create_policy.sgml"> +<!ENTITY createPublication SYSTEM "create_publication.sgml"> <!ENTITY createRole SYSTEM "create_role.sgml"> <!ENTITY createRule SYSTEM "create_rule.sgml"> <!ENTITY createSchema SYSTEM "create_schema.sgml"> <!ENTITY createSequence SYSTEM "create_sequence.sgml"> <!ENTITY createServer SYSTEM "create_server.sgml"> +<!ENTITY createStatistics SYSTEM "create_statistics.sgml"> +<!ENTITY createSubscription SYSTEM "create_subscription.sgml"> <!ENTITY createTable SYSTEM "create_table.sgml"> <!ENTITY createTableAs SYSTEM "create_table_as.sgml"> <!ENTITY createTableSpace SYSTEM "create_tablespace.sgml"> @@ -123,11 +129,14 @@ Complete list of usable sgml source files in this directory. <!ENTITY dropOperatorFamily SYSTEM "drop_opfamily.sgml"> <!ENTITY dropOwned SYSTEM "drop_owned.sgml"> <!ENTITY dropPolicy SYSTEM "drop_policy.sgml"> +<!ENTITY dropPublication SYSTEM "drop_publication.sgml"> <!ENTITY dropRole SYSTEM "drop_role.sgml"> <!ENTITY dropRule SYSTEM "drop_rule.sgml"> <!ENTITY dropSchema SYSTEM "drop_schema.sgml"> <!ENTITY dropSequence SYSTEM "drop_sequence.sgml"> <!ENTITY dropServer SYSTEM "drop_server.sgml"> +<!ENTITY dropStatistics SYSTEM "drop_statistics.sgml"> +<!ENTITY dropSubscription SYSTEM "drop_subscription.sgml"> <!ENTITY dropTable SYSTEM "drop_table.sgml"> <!ENTITY dropTableSpace SYSTEM "drop_tablespace.sgml"> <!ENTITY dropTransform SYSTEM "drop_transform.sgml"> @@ -186,10 +195,8 @@ Complete list of usable sgml source files in this directory. <!-- applications and utilities --> <!ENTITY clusterdb SYSTEM "clusterdb.sgml"> <!ENTITY createdb SYSTEM "createdb.sgml"> -<!ENTITY createlang SYSTEM "createlang.sgml"> <!ENTITY createuser SYSTEM "createuser.sgml"> <!ENTITY dropdb SYSTEM "dropdb.sgml"> -<!ENTITY droplang SYSTEM "droplang.sgml"> <!ENTITY dropuser SYSTEM "dropuser.sgml"> <!ENTITY ecpgRef SYSTEM "ecpg-ref.sgml"> <!ENTITY gtm system "gtm.sgml"> @@ -206,15 +213,15 @@ Complete list of usable sgml source files in this directory. <!ENTITY pgDump SYSTEM "pg_dump.sgml"> <!ENTITY pgDumpall SYSTEM "pg_dumpall.sgml"> <!ENTITY pgIsready SYSTEM "pg_isready.sgml"> -<!ENTITY pgReceivexlog SYSTEM "pg_receivexlog.sgml"> +<!ENTITY pgReceivewal SYSTEM "pg_receivewal.sgml"> <!ENTITY pgRecvlogical SYSTEM "pg_recvlogical.sgml"> -<!ENTITY pgResetxlog SYSTEM "pg_resetxlog.sgml"> +<!ENTITY pgResetwal SYSTEM "pg_resetwal.sgml"> <!ENTITY pgRestore SYSTEM "pg_restore.sgml"> <!ENTITY pgRewind SYSTEM "pg_rewind.sgml"> <!ENTITY pgtestfsync SYSTEM "pgtestfsync.sgml"> <!ENTITY pgtesttiming SYSTEM "pgtesttiming.sgml"> <!ENTITY pgupgrade SYSTEM "pgupgrade.sgml"> -<!ENTITY pgxlogdump SYSTEM "pg_xlogdump.sgml"> +<!ENTITY pgwaldump SYSTEM "pg_waldump.sgml"> <!ENTITY postgres SYSTEM "postgres-ref.sgml"> <!ENTITY postmaster SYSTEM "postmaster.sgml"> <!ENTITY psqlRef SYSTEM "psql-ref.sgml"> diff --git a/doc/src/sgml/ref/alter_collation.sgml b/doc/src/sgml/ref/alter_collation.sgml index 6708c7e10e..71cf4de802 100644 --- a/doc/src/sgml/ref/alter_collation.sgml +++ b/doc/src/sgml/ref/alter_collation.sgml @@ -21,6 +21,8 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> +ALTER COLLATION <replaceable>name</replaceable> REFRESH VERSION + ALTER COLLATION <replaceable>name</replaceable> RENAME TO <replaceable>new_name</replaceable> ALTER COLLATION <replaceable>name</replaceable> OWNER TO { <replaceable>new_owner</replaceable> | CURRENT_USER | SESSION_USER } ALTER COLLATION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_schema</replaceable> @@ -85,9 +87,63 @@ ALTER COLLATION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_sche </para> </listitem> </varlistentry> + + <varlistentry> + <term><literal>REFRESH VERSION</literal></term> + <listitem> + <para> + Updated the collation version. + See <xref linkend="sql-altercollation-notes" + endterm="sql-altercollation-notes-title"> below. + </para> + </listitem> + </varlistentry> </variablelist> </refsect1> + <refsect1 id="sql-altercollation-notes"> + <title id="sql-altercollation-notes-title">Notes</title> + + <para> + When using collations provided by the ICU library, the ICU-specific version + of the collator is recorded in the system catalog when the collation object + is created. When the collation is then used, the current version is + checked against the recorded version, and a warning is issued when there is + a mismatch, for example: +<screen> +WARNING: ICU collator version mismatch +DETAIL: The database was created using version 1.2.3.4, the library provides version 2.3.4.5. +HINT: Rebuild all objects affected by this collation and run ALTER COLLATION pg_catalog."xx-x-icu" REFRESH VERSION, or build PostgreSQL with the right version of ICU. +</screen> + A change in collation definitions can lead to corrupt indexes and other + problems where the database system relies on stored objects having a + certain sort order. Generally, this should be avoided, but it can happen + in legitimate circumstances, such as when + using <command>pg_upgrade</command> to upgrade to server binaries linked + with a newer version of ICU. When this happens, all objects depending on + the collation should be rebuilt, for example, + using <command>REINDEX</command>. When that is done, the collation version + can be refreshed using the command <literal>ALTER COLLATION ... REFRESH + VERSION</literal>. This will update the system catalog to record the + current collator version and will make the warning go away. Note that this + does not actually check whether all affected objects have been rebuilt + correctly. + </para> + + <para> + The following query can be used to identify all collations in the current + database that need to be refreshed and the objects that depend on them: +<programlisting><![CDATA[ +SELECT pg_describe_object(refclassid, refobjid, refobjsubid) AS "Collation", + pg_describe_object(classid, objid, objsubid) AS "Object" + FROM pg_depend d JOIN pg_collation c + ON refclassid = 'pg_collation'::regclass AND refobjid = c.oid + WHERE c.collversion <> pg_collation_actual_version(c.oid) + ORDER BY 1, 2; +]]></programlisting> + </para> + </refsect1> + <refsect1> <title>Examples</title> diff --git a/doc/src/sgml/ref/alter_default_privileges.sgml b/doc/src/sgml/ref/alter_default_privileges.sgml index 04064d399c..e3363f868a 100644 --- a/doc/src/sgml/ref/alter_default_privileges.sgml +++ b/doc/src/sgml/ref/alter_default_privileges.sgml @@ -46,6 +46,10 @@ GRANT { USAGE | ALL [ PRIVILEGES ] } ON TYPES TO { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...] [ WITH GRANT OPTION ] +GRANT { USAGE | CREATE | ALL [ PRIVILEGES ] } + ON SCHEMAS + TO { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...] [ WITH GRANT OPTION ] + REVOKE [ GRANT OPTION FOR ] { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER } [, ...] | ALL [ PRIVILEGES ] } @@ -71,6 +75,12 @@ REVOKE [ GRANT OPTION FOR ] ON TYPES FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...] [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { USAGE | CREATE | ALL [ PRIVILEGES ] } + ON SCHEMAS + FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...] + [ CASCADE | RESTRICT ] </synopsis> </refsynopsisdiv> @@ -81,8 +91,9 @@ REVOKE [ GRANT OPTION FOR ] <command>ALTER DEFAULT PRIVILEGES</> allows you to set the privileges that will be applied to objects created in the future. (It does not affect privileges assigned to already-existing objects.) Currently, - only the privileges for tables (including views and foreign tables), - sequences, functions, and types (including domains) can be altered. + only the privileges for schemas, tables (including views and foreign + tables), sequences, functions, and types (including domains) can be + altered. </para> <para> @@ -125,6 +136,8 @@ REVOKE [ GRANT OPTION FOR ] are altered for objects later created in that schema. If <literal>IN SCHEMA</> is omitted, the global default privileges are altered. + <literal>IN SCHEMA</> is not allowed when using <literal>ON SCHEMAS</> + as schemas can't be nested. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/alter_domain.sgml b/doc/src/sgml/ref/alter_domain.sgml index 74dda73c69..95a822aef6 100644 --- a/doc/src/sgml/ref/alter_domain.sgml +++ b/doc/src/sgml/ref/alter_domain.sgml @@ -54,7 +54,7 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable> <variablelist> <varlistentry> - <term>SET/DROP DEFAULT</term> + <term><literal>SET</literal>/<literal>DROP DEFAULT</literal></term> <listitem> <para> These forms set or remove the default value for a domain. Note @@ -65,7 +65,7 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable> </varlistentry> <varlistentry> - <term>SET/DROP NOT NULL</term> + <term><literal>SET</literal>/<literal>DROP NOT NULL</literal></term> <listitem> <para> These forms change whether a domain is marked to allow NULL @@ -76,7 +76,7 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable> </varlistentry> <varlistentry> - <term>ADD <replaceable class="PARAMETER">domain_constraint</replaceable> [ NOT VALID ]</term> + <term><literal>ADD <replaceable class="PARAMETER">domain_constraint</replaceable> [ NOT VALID ]</literal></term> <listitem> <para> This form adds a new constraint to a domain using the same syntax as @@ -94,7 +94,7 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable> </varlistentry> <varlistentry> - <term>DROP CONSTRAINT [ IF EXISTS ]</term> + <term><literal>DROP CONSTRAINT [ IF EXISTS ]</literal></term> <listitem> <para> This form drops constraints on a domain. @@ -105,7 +105,7 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable> </varlistentry> <varlistentry> - <term>RENAME CONSTRAINT</term> + <term><literal>RENAME CONSTRAINT</literal></term> <listitem> <para> This form changes the name of a constraint on a domain. @@ -114,7 +114,7 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable> </varlistentry> <varlistentry> - <term>VALIDATE CONSTRAINT</term> + <term><literal>VALIDATE CONSTRAINT</literal></term> <listitem> <para> This form validates a constraint previously added as @@ -125,7 +125,7 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable> </varlistentry> <varlistentry> - <term>OWNER</term> + <term><literal>OWNER</literal></term> <listitem> <para> This form changes the owner of the domain to the specified user. @@ -143,7 +143,7 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable> </varlistentry> <varlistentry> - <term>SET SCHEMA</term> + <term><literal>SET SCHEMA</literal></term> <listitem> <para> This form changes the schema of the domain. Any constraints diff --git a/doc/src/sgml/ref/alter_extension.sgml b/doc/src/sgml/ref/alter_extension.sgml index 7141ee352e..a7c0927d1c 100644 --- a/doc/src/sgml/ref/alter_extension.sgml +++ b/doc/src/sgml/ref/alter_extension.sgml @@ -30,6 +30,7 @@ ALTER EXTENSION <replaceable class="PARAMETER">name</replaceable> DROP <replacea <phrase>where <replaceable class="PARAMETER">member_object</replaceable> is:</phrase> + ACCESS METHOD <replaceable class="PARAMETER">object_name</replaceable> | AGGREGATE <replaceable class="PARAMETER">aggregate_name</replaceable> ( <replaceable>aggregate_signature</replaceable> ) | CAST (<replaceable>source_type</replaceable> AS <replaceable>target_type</replaceable>) | COLLATION <replaceable class="PARAMETER">object_name</replaceable> | @@ -38,7 +39,7 @@ ALTER EXTENSION <replaceable class="PARAMETER">name</replaceable> DROP <replacea EVENT TRIGGER <replaceable class="PARAMETER">object_name</replaceable> | FOREIGN DATA WRAPPER <replaceable class="PARAMETER">object_name</replaceable> | FOREIGN TABLE <replaceable class="PARAMETER">object_name</replaceable> | - FUNCTION <replaceable class="PARAMETER">function_name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) | + FUNCTION <replaceable class="PARAMETER">function_name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] | MATERIALIZED VIEW <replaceable class="PARAMETER">object_name</replaceable> | OPERATOR <replaceable class="PARAMETER">operator_name</replaceable> (<replaceable class="PARAMETER">left_type</replaceable>, <replaceable class="PARAMETER">right_type</replaceable>) | OPERATOR CLASS <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> | diff --git a/doc/src/sgml/ref/alter_function.sgml b/doc/src/sgml/ref/alter_function.sgml index 0388d06b95..168eeb7c52 100644 --- a/doc/src/sgml/ref/alter_function.sgml +++ b/doc/src/sgml/ref/alter_function.sgml @@ -21,15 +21,15 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> -ALTER FUNCTION <replaceable>name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) +ALTER FUNCTION <replaceable>name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] <replaceable class="PARAMETER">action</replaceable> [ ... ] [ RESTRICT ] -ALTER FUNCTION <replaceable>name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) +ALTER FUNCTION <replaceable>name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] RENAME TO <replaceable>new_name</replaceable> -ALTER FUNCTION <replaceable>name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) +ALTER FUNCTION <replaceable>name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] OWNER TO { <replaceable>new_owner</replaceable> | CURRENT_USER | SESSION_USER } -ALTER FUNCTION <replaceable>name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) +ALTER FUNCTION <replaceable>name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] SET SCHEMA <replaceable>new_schema</replaceable> -ALTER FUNCTION <replaceable>name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) +ALTER FUNCTION <replaceable>name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] DEPENDS ON EXTENSION <replaceable>extension_name</replaceable> <phrase>where <replaceable class="PARAMETER">action</replaceable> is one of:</phrase> @@ -75,7 +75,8 @@ ALTER FUNCTION <replaceable>name</replaceable> ( [ [ <replaceable class="paramet <term><replaceable class="parameter">name</replaceable></term> <listitem> <para> - The name (optionally schema-qualified) of an existing function. + The name (optionally schema-qualified) of an existing function. If no + argument list is specified, the name must be unique in its schema. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/alter_materialized_view.sgml b/doc/src/sgml/ref/alter_materialized_view.sgml index b5c44bfabf..b88f5ac00f 100644 --- a/doc/src/sgml/ref/alter_materialized_view.sgml +++ b/doc/src/sgml/ref/alter_materialized_view.sgml @@ -45,7 +45,6 @@ ALTER MATERIALIZED VIEW ALL IN TABLESPACE <replaceable class="parameter">name</r SET ( <replaceable class="PARAMETER">storage_parameter</replaceable> = <replaceable class="PARAMETER">value</replaceable> [, ... ] ) RESET ( <replaceable class="PARAMETER">storage_parameter</replaceable> [, ... ] ) OWNER TO { <replaceable class="PARAMETER">new_owner</replaceable> | CURRENT_USER | SESSION_USER } - SET TABLESPACE <replaceable class="PARAMETER">new_tablespace</replaceable> </synopsis> </refsynopsisdiv> diff --git a/doc/src/sgml/ref/alter_opfamily.sgml b/doc/src/sgml/ref/alter_opfamily.sgml index 4511c7f7b2..0bafe5b8f8 100644 --- a/doc/src/sgml/ref/alter_opfamily.sgml +++ b/doc/src/sgml/ref/alter_opfamily.sgml @@ -25,7 +25,7 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" { OPERATOR <replaceable class="parameter">strategy_number</replaceable> <replaceable class="parameter">operator_name</replaceable> ( <replaceable class="parameter">op_type</replaceable>, <replaceable class="parameter">op_type</replaceable> ) [ FOR SEARCH | FOR ORDER BY <replaceable class="parameter">sort_family_name</replaceable> ] | FUNCTION <replaceable class="parameter">support_number</replaceable> [ ( <replaceable class="parameter">op_type</replaceable> [ , <replaceable class="parameter">op_type</replaceable> ] ) ] - <replaceable class="parameter">function_name</replaceable> ( <replaceable class="parameter">argument_type</replaceable> [, ...] ) + <replaceable class="parameter">function_name</replaceable> [ ( <replaceable class="parameter">argument_type</replaceable> [, ...] ) ] } [, ... ] ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class="parameter">index_method</replaceable> DROP @@ -195,8 +195,9 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" <term><replaceable class="parameter">function_name</replaceable></term> <listitem> <para> - The name (optionally schema-qualified) of a function that is an - index method support procedure for the operator family. + The name (optionally schema-qualified) of a function that is an index + method support procedure for the operator family. If no argument list + is specified, the name must be unique in its schema. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/alter_policy.sgml b/doc/src/sgml/ref/alter_policy.sgml index a9b1541322..df347d180e 100644 --- a/doc/src/sgml/ref/alter_policy.sgml +++ b/doc/src/sgml/ref/alter_policy.sgml @@ -35,7 +35,12 @@ ALTER POLICY <replaceable class="parameter">name</replaceable> ON <replaceable c <para> <command>ALTER POLICY</command> changes the definition of an existing - row-level security policy. + row-level security policy. Note that <command>ALTER POLICY</command> + only allows the set of roles to which the policy applies and the + <literal>USING</literal> and <literal>WITH CHECK</literal> expressions to + be modified. To change other properties of a policy, such as the command + to which it applies or whether it is permissive or restrictive, the policy + must be dropped and recreated. </para> <para> diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml new file mode 100644 index 0000000000..7b8f114f54 --- /dev/null +++ b/doc/src/sgml/ref/alter_publication.sgml @@ -0,0 +1,152 @@ +<!-- +doc/src/sgml/ref/alter_publication.sgml +PostgreSQL documentation +--> + +<refentry id="SQL-ALTERPUBLICATION"> + <indexterm zone="sql-alterpublication"> + <primary>ALTER PUBLICATION</primary> + </indexterm> + + <refmeta> + <refentrytitle>ALTER PUBLICATION</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>ALTER PUBLICATION</refname> + <refpurpose>change the definition of a publication</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> ADD TABLE [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ * ] [, ...] +ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> SET TABLE [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ * ] [, ...] +ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> DROP TABLE [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ * ] [, ...] +ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> SET ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) +ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> OWNER TO { <replaceable>new_owner</replaceable> | CURRENT_USER | SESSION_USER } +ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>new_name</replaceable> +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + The first variant of this command listed in the synopsis can change + all of the publication properties specified in + <xref linkend="sql-createpublication">. Properties not mentioned in the + command retain their previous settings. + </para> + + <para> + To alter the owner, you must also be a direct or indirect member of the new + owning role. The new owner must have <literal>CREATE</literal> privilege on + the database. Also, the new owner of a <literal>FOR ALL TABLES</literal> + publication must be a superuser. However, a superuser can change the + ownership of a publication while circumventing these restrictions. + </para> + + <para> + The other variants of this command deal with the table membership of the + publication. The <literal>SET TABLE</literal> clause will replace the + list of tables in the publication with the specified one. + The <literal>ADD TABLE</literal> and + <literal>DROP TABLE</literal> will add and remove one or more tables from + the publication. + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">name</replaceable></term> + <listitem> + <para> + The name of an existing publication whose definition is to be altered. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">table_name</replaceable></term> + <listitem> + <para> + Name of an existing table. If <literal>ONLY</> is specified before the + table name, only that table is affected. If <literal>ONLY</> is not + specified, the table and all its descendant tables (if any) are + affected. Optionally, <literal>*</> can be specified after the table + name to explicitly indicate that descendant tables are included. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>SET ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term> + <listitem> + <para> + This clause alters publication parameters originally set by + <xref linkend="SQL-CREATEPUBLICATION">. See there for more information. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">new_owner</replaceable></term> + <listitem> + <para> + The user name of the new owner of the publication. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">new_name</replaceable></term> + <listitem> + <para> + The new name for the publication. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para> + Change the publication to publish only deletes and updates: +<programlisting> +ALTER PUBLICATION noinsert SET (publish = 'update, delete'); +</programlisting> + </para> + + <para> + Add some tables to the publication: +<programlisting> +ALTER PUBLICATION mypublication ADD TABLE users, departments; +</programlisting> + </para> + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + <command>ALTER PUBLICATION</command> is a <productname>PostgreSQL</> + extension. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-createpublication"></member> + <member><xref linkend="sql-droppublication"></member> + </simplelist> + </refsect1> +</refentry> diff --git a/doc/src/sgml/ref/alter_role.sgml b/doc/src/sgml/ref/alter_role.sgml index da36ad9696..8cd8602bc4 100644 --- a/doc/src/sgml/ref/alter_role.sgml +++ b/doc/src/sgml/ref/alter_role.sgml @@ -33,7 +33,7 @@ ALTER ROLE <replaceable class="PARAMETER">role_specification</replaceable> [ WIT | REPLICATION | NOREPLICATION | BYPASSRLS | NOBYPASSRLS | CONNECTION LIMIT <replaceable class="PARAMETER">connlimit</replaceable> - | [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>' + | [ ENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>' | VALID UNTIL '<replaceable class="PARAMETER">timestamp</replaceable>' ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>new_name</replaceable> @@ -134,7 +134,7 @@ ALTER ROLE { <replaceable class="PARAMETER">role_specification</replaceable> | A </varlistentry> <varlistentry> - <term>CURRENT_USER</term> + <term><literal>CURRENT_USER</literal></term> <listitem> <para> Alter the current user instead of an explicitly identified role. @@ -143,7 +143,7 @@ ALTER ROLE { <replaceable class="PARAMETER">role_specification</replaceable> | A </varlistentry> <varlistentry> - <term>SESSION_USER</term> + <term><literal>SESSION_USER</literal></term> <listitem> <para> Alter the current session user instead of an explicitly identified @@ -168,9 +168,7 @@ ALTER ROLE { <replaceable class="PARAMETER">role_specification</replaceable> | A <term><literal>BYPASSRLS</literal></term> <term><literal>NOBYPASSRLS</literal></term> <term><literal>CONNECTION LIMIT</literal> <replaceable class="parameter">connlimit</replaceable></term> - <term><literal>PASSWORD</> <replaceable class="parameter">password</replaceable></term> - <term><literal>ENCRYPTED</></term> - <term><literal>UNENCRYPTED</></term> + <term>[ <literal>ENCRYPTED</> ] <literal>PASSWORD</> <replaceable class="parameter">password</replaceable></term> <term><literal>VALID UNTIL</literal> '<replaceable class="parameter">timestamp</replaceable>'</term> <listitem> <para> diff --git a/doc/src/sgml/ref/alter_sequence.sgml b/doc/src/sgml/ref/alter_sequence.sgml index 47d3c8291f..30e5316b8c 100644 --- a/doc/src/sgml/ref/alter_sequence.sgml +++ b/doc/src/sgml/ref/alter_sequence.sgml @@ -23,7 +23,9 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> -ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [ INCREMENT [ BY ] <replaceable class="parameter">increment</replaceable> ] +ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> + [ AS <replaceable class="parameter">data_type</replaceable> ] + [ INCREMENT [ BY ] <replaceable class="parameter">increment</replaceable> ] [ MINVALUE <replaceable class="parameter">minvalue</replaceable> | NO MINVALUE ] [ MAXVALUE <replaceable class="parameter">maxvalue</replaceable> | NO MAXVALUE ] [ START [ WITH ] <replaceable class="parameter">start</replaceable> ] [ RESTART [ [ WITH ] <replaceable class="parameter">restart</replaceable> ] ] @@ -81,6 +83,31 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S </varlistentry> <varlistentry> + <term><replaceable class="parameter">data_type</replaceable></term> + <listitem> + <para> + The optional + clause <literal>AS <replaceable class="parameter">data_type</replaceable></literal> + changes the data type of the sequence. Valid types are + are <literal>smallint</literal>, <literal>integer</literal>, + and <literal>bigint</literal>. + </para> + + <para> + Changing the data type automatically changes the minimum and maximum + values of the sequence if and only if the previous minimum and maximum + values were the minimum or maximum value of the old data type (in + other words, if the sequence had been created using <literal>NO + MINVALUE</literal> or <literal>NO MAXVALUE</literal>, implicitly or + explicitly). Otherwise, the minimum and maximum values are preserved, + unless new values are given as part of the same command. If the + minimum and maximum values do not fit into the new data type, an error + will be generated. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><replaceable class="parameter">increment</replaceable></term> <listitem> <para> @@ -102,7 +129,7 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S class="parameter">minvalue</replaceable></literal> determines the minimum value a sequence can generate. If <literal>NO MINVALUE</literal> is specified, the defaults of 1 and - -2<superscript>63</>-1 for ascending and descending sequences, + the minimum value of the data type for ascending and descending sequences, respectively, will be used. If neither option is specified, the current minimum value will be maintained. </para> @@ -117,8 +144,8 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S The optional clause <literal>MAXVALUE <replaceable class="parameter">maxvalue</replaceable></literal> determines the maximum value for the sequence. If <literal>NO - MAXVALUE</literal> is specified, the defaults are - 2<superscript>63</>-1 and -1 for ascending and descending + MAXVALUE</literal> is specified, the defaults of + the maximum value of the data type and -1 for ascending and descending sequences, respectively, will be used. If neither option is specified, the current maximum value will be maintained. </para> @@ -153,6 +180,14 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S the start value that was recorded by <command>CREATE SEQUENCE</> or last set by <command>ALTER SEQUENCE START WITH</>. </para> + + <para> + Like a <function>setval</function> call, a <literal>RESTART</literal> + operation on a sequence is never rolled back, to avoid blocking of + concurrent transactions that obtain numbers from the same sequence. + (The other clauses cause ordinary catalog updates that can be rolled + back.) + </para> </listitem> </varlistentry> @@ -255,15 +290,6 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S <title>Notes</title> <para> - To avoid blocking of concurrent transactions that obtain numbers from the - same sequence, <command>ALTER SEQUENCE</command>'s effects on the sequence - generation parameters are never rolled back; those changes take effect - immediately and are not reversible. However, the <literal>OWNED BY</>, - <literal>OWNER TO</>, <literal>RENAME TO</>, and <literal>SET SCHEMA</> - clauses cause ordinary catalog updates that can be rolled back. - </para> - - <para> <command>ALTER SEQUENCE</command> will not immediately affect <function>nextval</> results in backends, other than the current one, that have preallocated (cached) sequence @@ -279,6 +305,13 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S </para> <para> + <command>ALTER SEQUENCE</command> blocks + concurrent <function>nextval</function>, <function>currval</function>, + <function>lastval</function>, and <command>setval</command> calls, except + if only the <literal>RESTART</literal> clause is used. + </para> + + <para> For historical reasons, <command>ALTER TABLE</command> can be used with sequences too; but the only variants of <command>ALTER TABLE</command> that are allowed with sequences are equivalent to the forms shown above. @@ -300,7 +333,7 @@ ALTER SEQUENCE serial RESTART WITH 105; <para> <command>ALTER SEQUENCE</command> conforms to the <acronym>SQL</acronym> - standard, except for the <literal>START WITH</>, + standard, except for the <literal>AS</literal>, <literal>START WITH</>, <literal>OWNED BY</>, <literal>OWNER TO</>, <literal>RENAME TO</>, and <literal>SET SCHEMA</literal> clauses, which are <productname>PostgreSQL</productname> extensions. diff --git a/doc/src/sgml/ref/alter_statistics.sgml b/doc/src/sgml/ref/alter_statistics.sgml new file mode 100644 index 0000000000..4f25669852 --- /dev/null +++ b/doc/src/sgml/ref/alter_statistics.sgml @@ -0,0 +1,117 @@ +<!-- +doc/src/sgml/ref/alter_statistics.sgml +PostgreSQL documentation +--> + +<refentry id="SQL-ALTERSTATISTICS"> + <indexterm zone="sql-alterstatistics"> + <primary>ALTER STATISTICS</primary> + </indexterm> + + <refmeta> + <refentrytitle>ALTER STATISTICS</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>ALTER STATISTICS</refname> + <refpurpose> + change the definition of an extended statistics object + </refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +ALTER STATISTICS <replaceable class="parameter">name</replaceable> OWNER TO { <replaceable class="PARAMETER">new_owner</replaceable> | CURRENT_USER | SESSION_USER } +ALTER STATISTICS <replaceable class="parameter">name</replaceable> RENAME TO <replaceable class="parameter">new_name</replaceable> +ALTER STATISTICS <replaceable class="parameter">name</replaceable> SET SCHEMA <replaceable class="parameter">new_schema</replaceable> +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>ALTER STATISTICS</command> changes the parameters of an existing + extended statistics object. Any parameters not specifically set in the + <command>ALTER STATISTICS</command> command retain their prior settings. + </para> + + <para> + You must own the statistics object to use <command>ALTER STATISTICS</>. + To change a statistics object's schema, you must also + have <literal>CREATE</> privilege on the new schema. + To alter the owner, you must also be a direct or indirect member of the new + owning role, and that role must have <literal>CREATE</literal> privilege on + the statistics object's schema. (These restrictions enforce that altering + the owner doesn't do anything you couldn't do by dropping and recreating + the statistics object. However, a superuser can alter ownership of any + statistics object anyway.) + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <para> + <variablelist> + <varlistentry> + <term><replaceable class="parameter">name</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of the statistics object to be + altered. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">new_owner</replaceable></term> + <listitem> + <para> + The user name of the new owner of the statistics object. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">new_name</replaceable></term> + <listitem> + <para> + The new name for the statistics object. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">new_schema</replaceable></term> + <listitem> + <para> + The new schema for the statistics object. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + There is no <command>ALTER STATISTICS</command> command in the SQL standard. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-createstatistics"></member> + <member><xref linkend="sql-dropstatistics"></member> + </simplelist> + </refsect1> + +</refentry> diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml new file mode 100644 index 0000000000..113e32bfd0 --- /dev/null +++ b/doc/src/sgml/ref/alter_subscription.sgml @@ -0,0 +1,216 @@ +<!-- +doc/src/sgml/ref/alter_subscription.sgml +PostgreSQL documentation +--> + +<refentry id="SQL-ALTERSUBSCRIPTION"> + <indexterm zone="sql-altersubscription"> + <primary>ALTER SUBSCRIPTION</primary> + </indexterm> + + <refmeta> + <refentrytitle>ALTER SUBSCRIPTION</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>ALTER SUBSCRIPTION</refname> + <refpurpose>change the definition of a subscription</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> CONNECTION '<replaceable>conninfo</replaceable>' +ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> SET PUBLICATION <replaceable class="PARAMETER">publication_name</replaceable> [, ...] { REFRESH [ WITH ( <replaceable class="PARAMETER">refresh_option</replaceable> [= <replaceable class="PARAMETER">value</replaceable>] [, ... ] ) ] | SKIP REFRESH } +ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> REFRESH PUBLICATION [ WITH ( <replaceable class="PARAMETER">refresh_option</replaceable> [= <replaceable class="PARAMETER">value</replaceable>] [, ... ] ) ] +ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> ENABLE +ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> DISABLE +ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> SET ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) +ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> OWNER TO { <replaceable>new_owner</replaceable> | CURRENT_USER | SESSION_USER } +ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>new_name</replaceable> +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>ALTER SUBSCRIPTION</command> can change most of the subscription + properties that can be specified + in <xref linkend="sql-createsubscription">. + </para> + + <para> + To alter the owner, you must also be a direct or indirect member of the + new owning role. The new owner has to be a superuser. + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">name</replaceable></term> + <listitem> + <para> + The name of a subscription whose properties are to be altered. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term> + <listitem> + <para> + This clause alters the connection property originally set by + <xref linkend="SQL-CREATESUBSCRIPTION">. See there for more + information. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>SET PUBLICATION <replaceable class="parameter">publication_name</replaceable></literal></term> + <listitem> + <para> + Changes list of subscribed publications. See + <xref linkend="SQL-CREATESUBSCRIPTION"> for more information. + </para> + + <para> + When <literal>REFRESH</literal> is specified, this command will also act + like <literal>REFRESH + PUBLICATION</literal>. <literal>refresh_option</literal> specifies + additional options for the refresh operation, as described + under <literal>REFRESH PUBLICATION</literal>. When + <literal>SKIP REFRESH</literal> is specified, the command will not try + to refresh table information. Note that + either <literal>REFRESH</literal> or <literal>SKIP REFRESH</literal> + must be specified. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>REFRESH PUBLICATION</literal></term> + <listitem> + <para> + Fetch missing table information from publisher. This will start + replication of tables that were added to the subscribed-to publications + since the last invocation of <command>REFRESH PUBLICATION</command> or + since <command>CREATE SUBSCRIPTION</command>. + </para> + + <para> + <literal>refresh_option</literal> specifies additional options for the + refresh operation. The supported options are: + + <variablelist> + <varlistentry> + <term><literal>copy_data</literal> (<type>boolean</type>)</term> + <listitem> + <para> + Specifies whether the existing data in the publications that are + being subscribed to should be copied once the replication starts. + The default is <literal>true</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ENABLE</literal></term> + <listitem> + <para> + Enables the previously disabled subscription, starting the logical + replication worker at the end of transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>DISABLE</literal></term> + <listitem> + <para> + Disables the running subscription, stopping the logical replication + worker at the end of transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>SET ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term> + <listitem> + <para> + This clause alters parameters originally set by + <xref linkend="SQL-CREATESUBSCRIPTION">. See there for more + information. The allowed options are <literal>slot_name</literal> and + <literal>synchronous_commit</literal> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">new_owner</replaceable></term> + <listitem> + <para> + The user name of the new owner of the subscription. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">new_name</replaceable></term> + <listitem> + <para> + The new name for the subscription. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para> + Change the publication subscribed by a subscription to + <literal>insert_only</literal>: +<programlisting> +ALTER SUBSCRIPTION mysub SET PUBLICATION insert_only REFRESH; +</programlisting> + </para> + + <para> + Disable (stop) the subscription: +<programlisting> +ALTER SUBSCRIPTION mysub DISABLE; +</programlisting> + </para> + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + <command>ALTER SUBSCRIPTION</command> is a <productname>PostgreSQL</> + extension. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-createsubscription"></member> + <member><xref linkend="sql-dropsubscription"></member> + <member><xref linkend="sql-createpublication"></member> + <member><xref linkend="sql-alterpublication"></member> + </simplelist> + </refsect1> +</refentry> diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml index 8deb80ab63..1dfbf6d3c8 100755 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -33,6 +33,10 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> SET SCHEMA <replaceable class="PARAMETER">new_schema</replaceable> ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable> [ OWNED BY <replaceable class="PARAMETER">role_name</replaceable> [, ... ] ] SET TABLESPACE <replaceable class="PARAMETER">new_tablespace</replaceable> [ NOWAIT ] +ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> + ATTACH PARTITION <replaceable class="PARAMETER">partition_name</replaceable> FOR VALUES <replaceable class="PARAMETER">partition_bound_spec</replaceable> +ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> + DETACH PARTITION <replaceable class="PARAMETER">partition_name</replaceable> <phrase>where <replaceable class="PARAMETER">action</replaceable> is one of:</phrase> @@ -42,6 +46,9 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable> ALTER [ COLUMN ] <replaceable class="PARAMETER">column_name</replaceable> SET DEFAULT <replaceable class="PARAMETER">expression</replaceable> ALTER [ COLUMN ] <replaceable class="PARAMETER">column_name</replaceable> DROP DEFAULT ALTER [ COLUMN ] <replaceable class="PARAMETER">column_name</replaceable> { SET | DROP } NOT NULL + ALTER [ COLUMN ] <replaceable class="PARAMETER">column_name</replaceable> ADD GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( <replaceable>sequence_options</replaceable> ) ] + ALTER [ COLUMN ] <replaceable class="PARAMETER">column_name</replaceable> { SET GENERATED { ALWAYS | BY DEFAULT } | SET <replaceable>sequence_option</replaceable> | RESTART [ [ WITH ] <replaceable class="parameter">restart</replaceable> ] } [...] + ALTER [ COLUMN ] <replaceable class="PARAMETER">column_name</replaceable> DROP IDENTITY [ IF EXISTS ] ALTER [ COLUMN ] <replaceable class="PARAMETER">column_name</replaceable> SET STATISTICS <replaceable class="PARAMETER">integer</replaceable> ALTER [ COLUMN ] <replaceable class="PARAMETER">column_name</replaceable> SET ( <replaceable class="PARAMETER">attribute_option</replaceable> = <replaceable class="PARAMETER">value</replaceable> [, ... ] ) ALTER [ COLUMN ] <replaceable class="PARAMETER">column_name</replaceable> RESET ( <replaceable class="PARAMETER">attribute_option</replaceable> [, ... ] ) @@ -115,9 +122,12 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable> <para> This form drops a column from a table. Indexes and table constraints involving the column will be automatically - dropped as well. You will need to say <literal>CASCADE</> if - anything outside the table depends on the column, for example, - foreign key references or views. + dropped as well. + Multivariate statistics referencing the dropped column will also be + removed if the removal of the column would cause the statistics to + contain data for only a single column. + You will need to say <literal>CASCADE</> if anything outside the table + depends on the column, for example, foreign key references or views. If <literal>IF EXISTS</literal> is specified and the column does not exist, no error is thrown. In this case a notice is issued instead. @@ -166,6 +176,49 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable> values or to reject null values. You can only use <literal>SET NOT NULL</> when the column contains no null values. </para> + + <para> + If this table is a partition, one cannot perform <literal>DROP NOT NULL</literal> + on a column if it is marked <literal>NOT NULL</literal> in the parent + table. To drop the <literal>NOT NULL</literal> constraint from all the + partitions, perform <literal>DROP NOT NULL</literal> on the parent + table. Even if there is no <literal>NOT NULL</> constraint on the + parent, such a constraint can still be added to individual partitions, + if desired; that is, the children can disallow nulls even if the parent + allows them, but not the other way around. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ADD GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY</literal></term> + <term><literal>SET GENERATED { ALWAYS | BY DEFAULT }</literal></term> + <term><literal>DROP IDENTITY [ IF EXISTS ]</literal></term> + <listitem> + <para> + These forms change whether a column is an identity column or change the + generation attribute of an existing identity column. + See <xref linkend="sql-createtable"> for details. + </para> + + <para> + If <literal>DROP IDENTITY IF EXISTS</literal> is specified and the + column is not an identity column, no error is thrown. In this case a + notice is issued instead. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>SET <replaceable>sequence_option</replaceable></literal></term> + <term><literal>RESTART</literal></term> + <listitem> + <para> + These forms alter the sequence that underlies an existing identity + column. <replaceable>sequence_option</replaceable> is an option + supported by <xref linkend="sql-altersequence"> such + as <literal>INCREMENT BY</literal>. + </para> </listitem> </varlistentry> @@ -558,10 +611,17 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable> That can be done with <link linkend="SQL-VACUUM">VACUUM FULL</>, <xref linkend="SQL-CLUSTER"> or one of the forms of <command>ALTER TABLE</> that forces a table rewrite. + For planner related parameters, changes will take effect from the next + time the table is locked so currently executing queries will not be + affected. </para> <para> - Changing fillfactor and autovacuum storage parameters acquires a <literal>SHARE UPDATE EXCLUSIVE</literal> lock. + <literal>SHARE UPDATE EXCLUSIVE</literal> lock will be taken for + fillfactor and autovacuum storage parameters, as well as the + following planner related parameters: + effective_io_concurrency, parallel_workers, seq_page_cost + random_page_cost, n_distinct and n_distinct_inherited. </para> <note> @@ -768,6 +828,47 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable> </listitem> </varlistentry> </variablelist> + <term><literal>ATTACH PARTITION <replaceable class="PARAMETER">partition_name</replaceable> FOR VALUES <replaceable class="PARAMETER">partition_bound_spec</replaceable></literal></term> + <listitem> + <para> + This form attaches an existing table (which might itself be partitioned) + as a partition of the target table using the same syntax for + <replaceable class="PARAMETER">partition_bound_spec</replaceable> as + <xref linkend="sql-createtable">. The partition bound specification + must correspond to the partitioning strategy and partition key of the + target table. The table to be attached must have all the same columns + as the target table and no more; moreover, the column types must also + match. Also, it must have all the <literal>NOT NULL</literal> and + <literal>CHECK</literal> constraints of the target table. Currently + <literal>UNIQUE</literal>, <literal>PRIMARY KEY</literal>, and + <literal>FOREIGN KEY</literal> constraints are not considered. + If any of the <literal>CHECK</literal> constraints of the table being + attached is marked <literal>NO INHERIT</literal>, the command will fail; + such a constraint must be recreated without the <literal>NO INHERIT</literal> + clause. + </para> + + <para> + If the new partition is a regular table, a full table scan is performed + to check that no existing row in the table violates the partition + constraint. It is possible to avoid this scan by adding a valid + <literal>CHECK</literal> constraint to the table that would allow only + the rows satisfying the desired partition constraint before running this + command. It will be determined using such a constraint that the table + need not be scanned to validate the partition constraint. This does not + work, however, if any of the partition keys is an expression and the + partition does not accept <literal>NULL</literal> values. If attaching + a list partition that will not accept <literal>NULL</literal> values, + also add <literal>NOT NULL</literal> constraint to the partition key + column, unless it's an expression. + </para> + + <para> + If the new partition is a foreign table, nothing is done to verify + that all the rows in the foreign table obey the partition constraint. + (See the discussion in <xref linkend="SQL-CREATEFOREIGNTABLE"> about + constraints on the foreign table.) + </para> </listitem> </varlistentry> @@ -802,14 +903,25 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable> </para> </listitem> </varlistentry> + <varlistentry> + <term><literal>DETACH PARTITION</literal> <replaceable class="PARAMETER">partition_name</replaceable></term> + <listitem> + <para> + This form detaches specified partition of the target table. The detached + partition continues to exist as a standalone table, but no longer has any + ties to the table from which it was detached. + </para> + </listitem> + </varlistentry> </variablelist> </para> <para> - All the actions except <literal>RENAME</literal>, - <literal>SET TABLESPACE</literal> and <literal>SET SCHEMA</literal> - can be combined into - a list of multiple alterations to apply in parallel. For example, it + All the forms of ALTER TABLE that act on a single table, except + <literal>RENAME</literal>, <literal>SET SCHEMA</literal>, + <literal>ATTACH PARTITION</literal>, and + <literal>DETACH PARTITION</literal> can be combined into + a list of multiple alterations to be applied together. For example, it is possible to add several columns and/or alter the type of several columns in a single command. This is particularly useful with large tables, since only one pass over the table need be made. @@ -819,8 +931,9 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable> You must own the table to use <command>ALTER TABLE</>. To change the schema or tablespace of a table, you must also have <literal>CREATE</literal> privilege on the new schema or tablespace. - To add the table as a new child of a parent table, you must own the - parent table as well. + To add the table as a new child of a parent table, you must own the parent + table as well. Also, to attach a table as a new partition of the table, + you must own the table being attached. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have <literal>CREATE</literal> privilege on the table's schema. (These restrictions enforce that altering the owner @@ -1054,6 +1167,25 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable> </listitem> </varlistentry> + <varlistentry> + <term><replaceable class="PARAMETER">partition_name</replaceable></term> + <listitem> + <para> + The name of the table to attach as a new partition or to detach from this table. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">partition_bound_spec</replaceable></term> + <listitem> + <para> + The partition bound specification for a new partition. Refer to + <xref linkend="sql-createtable"> for more details on the syntax of the same. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect1> @@ -1094,6 +1226,11 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable> </para> <para> + Similarly, when attaching a new partition it may be scanned to verify that + existing rows meet the partition constraint. + </para> + + <para> The main reason for providing the option to specify multiple changes in a single <command>ALTER TABLE</> is that multiple table scans or rewrites can thereby be combined into a single pass over the table. @@ -1144,11 +1281,15 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable> <para> If a table has any descendant tables, it is not permitted to add, - rename, or change the type of a column, or rename an inherited constraint - in the parent table without doing - the same to the descendants. That is, <command>ALTER TABLE ONLY</command> - will be rejected. This ensures that the descendants always have - columns matching the parent. + rename, or change the type of a column in the parent table without doing + same to the descendants. This ensures that the descendants always have + columns matching the parent. Similarly, a constraint cannot be renamed + in the parent without also renaming it in all descendants, so that + constraints also match between the parent and its descendants. + Also, because selecting from the parent also selects from its descendants, + a constraint on the parent cannot be marked valid unless it is also marked + valid for those descendants. In all of these cases, <command>ALTER TABLE + ONLY</command> will be rejected. </para> <para> @@ -1159,11 +1300,17 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable> COLUMN</literal> (i.e., <command>ALTER TABLE ONLY ... DROP COLUMN</command>) never removes any descendant columns, but instead marks them as independently defined rather than inherited. + A nonrecursive <literal>DROP COLUMN</literal> command will fail for a + partitioned table, because all partitions of a table must have the same + columns as the partitioning root. </para> <para> - The <literal>TRIGGER</>, <literal>CLUSTER</>, <literal>OWNER</>, - and <literal>TABLESPACE</> actions never recurse to descendant tables; + The actions for identity columns (<literal>ADD + GENERATED</literal>, <literal>SET</literal> etc., <literal>DROP + IDENTITY</literal>), as well as the actions + <literal>TRIGGER</>, <literal>CLUSTER</>, <literal>OWNER</>, + and <literal>TABLESPACE</> never recurse to descendant tables; that is, they always act as though <literal>ONLY</> were specified. Adding a constraint recurses only for <literal>CHECK</> constraints that are not marked <literal>NO INHERIT</>. @@ -1441,6 +1588,27 @@ ALTER TABLE distributors DELETE NODE (dn4, dn0); </programlisting> </para> + <para> + Attach a partition to range partitioned table: +<programlisting> +ALTER TABLE measurement + ATTACH PARTITION measurement_y2016m07 FOR VALUES FROM ('2016-07-01') TO ('2016-08-01'); +</programlisting></para> + + <para> + Attach a partition to list partitioned table: +<programlisting> +ALTER TABLE cities + ATTACH PARTITION cities_ab FOR VALUES IN ('a', 'b'); +</programlisting></para> + + <para> + Detach a partition from partitioned table: +<programlisting> +ALTER TABLE cities + DETACH PARTITION measurement_y2015m12; +</programlisting></para> + </refsect1> <refsect1> @@ -1448,8 +1616,9 @@ ALTER TABLE distributors DELETE NODE (dn4, dn0); <para> The forms <literal>ADD</literal> (without <literal>USING INDEX</literal>), - <literal>DROP</>, <literal>SET DEFAULT</>, - and <literal>SET DATA TYPE</literal> (without <literal>USING</literal>) + <literal>DROP [COLUMN]</>, <literal>DROP IDENTITY</literal>, <literal>RESTART</literal>, + <literal>SET DEFAULT</>, <literal>SET DATA TYPE</literal> (without <literal>USING</literal>), + <literal>SET GENERATED</literal>, and <literal>SET <replaceable>sequence_option</replaceable></literal> conform with the SQL standard. The other forms are <productname>PostgreSQL</productname> extensions of the SQL standard. Also, the ability to specify more than one manipulation in a single diff --git a/doc/src/sgml/ref/alter_tablespace.sgml b/doc/src/sgml/ref/alter_tablespace.sgml index d9b2a133b1..2f41105001 100644 --- a/doc/src/sgml/ref/alter_tablespace.sgml +++ b/doc/src/sgml/ref/alter_tablespace.sgml @@ -83,14 +83,15 @@ ALTER TABLESPACE <replaceable>name</replaceable> RESET ( <replaceable class="PAR <listitem> <para> A tablespace parameter to be set or reset. Currently, the only - available parameters are <varname>seq_page_cost</> and - <varname>random_page_cost</>. Setting either value for a particular - tablespace will override the planner's usual estimate of the cost of - reading pages from tables in that tablespace, as established by - the configuration parameters of the same name (see - <xref linkend="guc-seq-page-cost">, - <xref linkend="guc-random-page-cost">). This may be useful if one - tablespace is located on a disk which is faster or slower than the + available parameters are <varname>seq_page_cost</>, + <varname>random_page_cost</> and <varname>effective_io_concurrency</>. + Setting either value for a particular tablespace will override the + planner's usual estimate of the cost of reading pages from tables in + that tablespace, as established by the configuration parameters of the + same name (see <xref linkend="guc-seq-page-cost">, + <xref linkend="guc-random-page-cost">, + <xref linkend="guc-effective-io-concurrency">). This may be useful if + one tablespace is located on a disk which is faster or slower than the remainder of the I/O subsystem. </para> </listitem> diff --git a/doc/src/sgml/ref/alter_type.sgml b/doc/src/sgml/ref/alter_type.sgml index 9789881a5c..fdb4f3367d 100644 --- a/doc/src/sgml/ref/alter_type.sgml +++ b/doc/src/sgml/ref/alter_type.sgml @@ -28,7 +28,8 @@ ALTER TYPE <replaceable class="PARAMETER">name</replaceable> OWNER TO { <replace ALTER TYPE <replaceable class="PARAMETER">name</replaceable> RENAME ATTRIBUTE <replaceable class="PARAMETER">attribute_name</replaceable> TO <replaceable class="PARAMETER">new_attribute_name</replaceable> [ CASCADE | RESTRICT ] ALTER TYPE <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable class="PARAMETER">new_name</replaceable> ALTER TYPE <replaceable class="PARAMETER">name</replaceable> SET SCHEMA <replaceable class="PARAMETER">new_schema</replaceable> -ALTER TYPE <replaceable class="PARAMETER">name</replaceable> ADD VALUE [ IF NOT EXISTS ] <replaceable class="PARAMETER">new_enum_value</replaceable> [ { BEFORE | AFTER } <replaceable class="PARAMETER">existing_enum_value</replaceable> ] +ALTER TYPE <replaceable class="PARAMETER">name</replaceable> ADD VALUE [ IF NOT EXISTS ] <replaceable class="PARAMETER">new_enum_value</replaceable> [ { BEFORE | AFTER } <replaceable class="PARAMETER">neighbor_enum_value</replaceable> ] +ALTER TYPE <replaceable class="PARAMETER">name</replaceable> RENAME VALUE <replaceable class="PARAMETER">existing_enum_value</replaceable> TO <replaceable class="PARAMETER">new_enum_value</replaceable> <phrase>where <replaceable class="PARAMETER">action</replaceable> is one of:</phrase> @@ -124,21 +125,13 @@ ALTER TYPE <replaceable class="PARAMETER">name</replaceable> ADD VALUE [ IF NOT </varlistentry> <varlistentry> - <term><literal>CASCADE</literal></term> + <term><literal>RENAME VALUE</literal></term> <listitem> <para> - Automatically propagate the operation to typed tables of the - type being altered, and their descendants. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>RESTRICT</literal></term> - <listitem> - <para> - Refuse the operation if the type being altered is the type of a - typed table. This is the default. + This form renames a value of an enum type. + The value's place in the enum's ordering is not affected. + An error will occur if the specified value is not present or the new + name is already present. </para> </listitem> </varlistentry> @@ -241,14 +234,15 @@ ALTER TYPE <replaceable class="PARAMETER">name</replaceable> ADD VALUE [ IF NOT <term><replaceable class="PARAMETER">new_enum_value</replaceable></term> <listitem> <para> - The new value to be added to an enum type's list of values. + The new value to be added to an enum type's list of values, + or the new name to be given to an existing value. Like all enum literals, it needs to be quoted. </para> </listitem> </varlistentry> <varlistentry> - <term><replaceable class="PARAMETER">existing_enum_value</replaceable></term> + <term><replaceable class="PARAMETER">neighbor_enum_value</replaceable></term> <listitem> <para> The existing enum value that the new value should be added immediately @@ -258,6 +252,36 @@ ALTER TYPE <replaceable class="PARAMETER">name</replaceable> ADD VALUE [ IF NOT </listitem> </varlistentry> + <varlistentry> + <term><replaceable class="PARAMETER">existing_enum_value</replaceable></term> + <listitem> + <para> + The existing enum value that should be renamed. + Like all enum literals, it needs to be quoted. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically propagate the operation to typed tables of the + type being altered, and their descendants. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse the operation if the type being altered is the type of a + typed table. This is the default. + </para> + </listitem> + </varlistentry> + </variablelist> </para> </refsect1> @@ -266,8 +290,12 @@ ALTER TYPE <replaceable class="PARAMETER">name</replaceable> ADD VALUE [ IF NOT <title>Notes</title> <para> - <command>ALTER TYPE ... ADD VALUE</> (the form that adds a new value to an - enum type) cannot be executed inside a transaction block. + If <command>ALTER TYPE ... ADD VALUE</> (the form that adds a new value to + an enum type) is executed inside a transaction block, the new value cannot + be used until after the transaction has been committed, except in the case + that the enum type itself was created earlier in the same transaction. + Likewise, when a pre-existing enum value is renamed, the transaction must + be committed before the renamed value can be used. </para> <para> @@ -321,7 +349,15 @@ ALTER TYPE compfoo ADD ATTRIBUTE f3 int; To add a new value to an enum type in a particular sort position: <programlisting> ALTER TYPE colors ADD VALUE 'orange' AFTER 'red'; -</programlisting></para> +</programlisting> + </para> + + <para> + To rename an enum value: +<programlisting> +ALTER TYPE colors RENAME VALUE 'purple' TO 'mauve'; +</programlisting> + </para> </refsect1> <refsect1> diff --git a/doc/src/sgml/ref/alter_user.sgml b/doc/src/sgml/ref/alter_user.sgml index 5962a8e166..9b8a39b376 100644 --- a/doc/src/sgml/ref/alter_user.sgml +++ b/doc/src/sgml/ref/alter_user.sgml @@ -33,7 +33,7 @@ ALTER USER <replaceable class="PARAMETER">role_specification</replaceable> [ WIT | REPLICATION | NOREPLICATION | BYPASSRLS | NOBYPASSRLS | CONNECTION LIMIT <replaceable class="PARAMETER">connlimit</replaceable> - | [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>' + | [ ENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>' | VALID UNTIL '<replaceable class="PARAMETER">timestamp</replaceable>' ALTER USER <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>new_name</replaceable> diff --git a/doc/src/sgml/ref/alter_user_mapping.sgml b/doc/src/sgml/ref/alter_user_mapping.sgml index 4b8b2ddc55..e4069288d7 100644 --- a/doc/src/sgml/ref/alter_user_mapping.sgml +++ b/doc/src/sgml/ref/alter_user_mapping.sgml @@ -93,9 +93,9 @@ ALTER USER MAPPING FOR { <replaceable class="parameter">user_name</replaceable> <title>Examples</title> <para> - Change the password for user mapping <literal>bob</>, server<literal> foo</>: + Change the password for user mapping <literal>bob</>, server <literal>foo</>: <programlisting> -ALTER USER MAPPING FOR bob SERVER foo OPTIONS (user 'bob', password 'public'); +ALTER USER MAPPING FOR bob SERVER foo OPTIONS (SET password 'public'); </programlisting></para> </refsect1> diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml index f2f3f97e0a..ef0a3d0f92 100644 --- a/doc/src/sgml/ref/analyze.sgml +++ b/doc/src/sgml/ref/analyze.sgml @@ -75,8 +75,11 @@ values are used as they are. <listitem> <para> The name (possibly schema-qualified) of a specific table to - analyze. If omitted, all regular tables (but not foreign tables) - in the current database are analyzed. + analyze. If omitted, all regular tables, partitioned tables, and + materialized views in the current database are analyzed (but not + foreign tables). If the specified table is a partitioned table, both the + inheritance statistics of the partitioned table as a whole and + statistics of the individual partitions are updated. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/checkpoint.sgml b/doc/src/sgml/ref/checkpoint.sgml index e51dd9f9cf..cd18ac4c58 100644 --- a/doc/src/sgml/ref/checkpoint.sgml +++ b/doc/src/sgml/ref/checkpoint.sgml @@ -13,7 +13,7 @@ <refnamediv> <refname>CHECKPOINT</refname> - <refpurpose>force a transaction log checkpoint</refpurpose> + <refpurpose>force a write-ahead log checkpoint</refpurpose> </refnamediv> <refsynopsisdiv> @@ -26,7 +26,7 @@ CHECKPOINT <title>Description</title> <para> - A checkpoint is a point in the transaction log sequence at which + A checkpoint is a point in the write-ahead log sequence at which all data files have been updated to reflect the information in the log. All data files will be flushed to disk. Refer to <xref linkend="wal-configuration"> for more details about what happens diff --git a/doc/src/sgml/ref/clusterdb.sgml b/doc/src/sgml/ref/clusterdb.sgml index c13d74853e..67582fd6e6 100644 --- a/doc/src/sgml/ref/clusterdb.sgml +++ b/doc/src/sgml/ref/clusterdb.sgml @@ -316,7 +316,7 @@ PostgreSQL documentation <literal>foo</literal> in a database named <literal>xyzzy</literal>: <screen> -<prompt>$ </prompt><userinput>clusterdb --table foo xyzzy</userinput> +<prompt>$ </prompt><userinput>clusterdb --table=foo xyzzy</userinput> </screen></para> </refsect1> diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml index c1cf587cb2..df328117f1 100644 --- a/doc/src/sgml/ref/comment.sgml +++ b/doc/src/sgml/ref/comment.sgml @@ -37,7 +37,7 @@ COMMENT ON EVENT TRIGGER <replaceable class="PARAMETER">object_name</replaceable> | FOREIGN DATA WRAPPER <replaceable class="PARAMETER">object_name</replaceable> | FOREIGN TABLE <replaceable class="PARAMETER">object_name</replaceable> | - FUNCTION <replaceable class="PARAMETER">function_name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) | + FUNCTION <replaceable class="PARAMETER">function_name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] | INDEX <replaceable class="PARAMETER">object_name</replaceable> | LARGE OBJECT <replaceable class="PARAMETER">large_object_oid</replaceable> | MATERIALIZED VIEW <replaceable class="PARAMETER">object_name</replaceable> | @@ -46,11 +46,14 @@ COMMENT ON OPERATOR FAMILY <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> | POLICY <replaceable class="PARAMETER">policy_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> | [ PROCEDURAL ] LANGUAGE <replaceable class="PARAMETER">object_name</replaceable> | + PUBLICATION <replaceable class="PARAMETER">object_name</replaceable> | ROLE <replaceable class="PARAMETER">object_name</replaceable> | RULE <replaceable class="PARAMETER">rule_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> | SCHEMA <replaceable class="PARAMETER">object_name</replaceable> | SEQUENCE <replaceable class="PARAMETER">object_name</replaceable> | SERVER <replaceable class="PARAMETER">object_name</replaceable> | + STATISTICS <replaceable class="PARAMETER">object_name</replaceable> | + SUBSCRIPTION <replaceable class="PARAMETER">object_name</replaceable> | TABLE <replaceable class="PARAMETER">object_name</replaceable> | TABLESPACE <replaceable class="PARAMETER">object_name</replaceable> | TEXT SEARCH CONFIGURATION <replaceable class="PARAMETER">object_name</replaceable> | @@ -125,8 +128,8 @@ COMMENT ON The name of the object to be commented. Names of tables, aggregates, collations, conversions, domains, foreign tables, functions, indexes, operators, operator classes, operator families, sequences, - text search objects, types, and views can be schema-qualified. - When commenting on a column, + statistics, text search objects, types, and views can be + schema-qualified. When commenting on a column, <replaceable class="parameter">relation_name</replaceable> must refer to a table, view, composite type, or foreign table. </para> @@ -327,6 +330,7 @@ COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records'; COMMENT ON SCHEMA my_schema IS 'Departmental data'; COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys'; COMMENT ON SERVER myserver IS 'my foreign server'; +COMMENT ON STATISTICS my_statistics IS 'Improves planner row estimations'; COMMENT ON TABLE my_schema.my_table IS 'Employee Information'; COMMENT ON TABLESPACE my_tablespace IS 'Tablespace for indexes'; COMMENT ON TEXT SEARCH CONFIGURATION my_config IS 'Special word filtering'; diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml index 783e7306f5..413e69f4c5 100644 --- a/doc/src/sgml/ref/copy.sgml +++ b/doc/src/sgml/ref/copy.sgml @@ -401,9 +401,15 @@ COPY <replaceable class="parameter">count</replaceable> <title>Notes</title> <para> - <command>COPY</command> can only be used with plain tables, not + <command>COPY TO</command> can only be used with plain tables, not with views. However, you can write <literal>COPY (SELECT * FROM - <replaceable class="parameter">viewname</replaceable>) TO ...</literal>. + <replaceable class="parameter">viewname</replaceable>) TO ...</literal> + to copy the current contents of a view. + </para> + + <para> + <command>COPY FROM</command> can be used with plain tables and with views + that have <literal>INSTEAD OF INSERT</> triggers. </para> <para> @@ -425,6 +431,15 @@ COPY <replaceable class="parameter">count</replaceable> </para> <para> + If row-level security is enabled for the table, the relevant + <command>SELECT</command> policies will apply to <literal>COPY + <replaceable class="parameter">table</> TO</literal> statements. + Currently, <command>COPY FROM</command> is not supported for tables + with row-level security. Use equivalent <command>INSERT</command> + statements instead. + </para> + + <para> Files named in a <command>COPY</command> command are read or written directly by the server, not by the client application. Therefore, they must reside on or be accessible to the database server machine, @@ -471,6 +486,13 @@ COPY <replaceable class="parameter">count</replaceable> </para> <para> + For identity columns, the <command>COPY FROM</command> command will always + write the column values provided in the input data, like + the <command>INPUT</command> option <literal>OVERRIDING SYSTEM + VALUE</literal>. + </para> + + <para> <command>COPY</command> input and output is affected by <varname>DateStyle</varname>. To ensure portability to other <productname>PostgreSQL</productname> installations that might use diff --git a/doc/src/sgml/ref/create_access_method.sgml b/doc/src/sgml/ref/create_access_method.sgml index 3c091f8021..0a30e6ea3c 100644 --- a/doc/src/sgml/ref/create_access_method.sgml +++ b/doc/src/sgml/ref/create_access_method.sgml @@ -57,29 +57,28 @@ CREATE ACCESS METHOD <replaceable class="parameter">name</replaceable> </varlistentry> <varlistentry> - <term><literal>access_method_type</literal></term> + <term><replaceable class="parameter">access_method_type</replaceable></term> <listitem> <para> - This clause specifies type of access method to define. + This clause specifies the type of access method to define. Only <literal>INDEX</literal> is supported at present. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>HANDLER <replaceable class="parameter">handler_function</replaceable></literal></term> + <term><replaceable class="parameter">handler_function</replaceable></term> <listitem> - <para><replaceable class="parameter">handler_function</replaceable> is the - name of a previously registered function that will be called to - retrieve the struct which contains required parameters and functions - of access method to the core. The handler function must take single - argument of type <type>internal</>, and its return type depends on the - type of access method; for <literal>INDEX</literal> access methods, it - must be <type>index_am_handler</type>. - </para> - <para> - See <xref linkend="index-api"> for index access methods API. + <replaceable class="parameter">handler_function</replaceable> is the + name (possibly schema-qualified) of a previously registered function + that represents the access method. The handler function must be + declared to take a single argument of type <type>internal</>, + and its return type depends on the type of access method; + for <literal>INDEX</literal> access methods, it must + be <type>index_am_handler</type>. The C-level API that the handler + function must implement varies depending on the type of access method. + The index access method API is described in <xref linkend="indexam">. </para> </listitem> </varlistentry> @@ -90,7 +89,7 @@ CREATE ACCESS METHOD <replaceable class="parameter">name</replaceable> <title>Examples</title> <para> - Create an access method <literal>heptree</> with + Create an index access method <literal>heptree</> with handler function <literal>heptree_handler</>: <programlisting> CREATE ACCESS METHOD heptree TYPE INDEX HANDLER heptree_handler; diff --git a/doc/src/sgml/ref/create_cast.sgml b/doc/src/sgml/ref/create_cast.sgml index 11266755e5..a7d13edc22 100644 --- a/doc/src/sgml/ref/create_cast.sgml +++ b/doc/src/sgml/ref/create_cast.sgml @@ -19,7 +19,7 @@ <refsynopsisdiv> <synopsis> CREATE CAST (<replaceable>source_type</replaceable> AS <replaceable>target_type</replaceable>) - WITH FUNCTION <replaceable>function_name</replaceable> (<replaceable>argument_type</replaceable> [, ...]) + WITH FUNCTION <replaceable>function_name</replaceable> [ (<replaceable>argument_type</replaceable> [, ...]) ] [ AS ASSIGNMENT | AS IMPLICIT ] CREATE CAST (<replaceable>source_type</replaceable> AS <replaceable>target_type</replaceable>) @@ -192,7 +192,7 @@ SELECT CAST ( 2 AS numeric ) + 4.0; </varlistentry> <varlistentry> - <term><replaceable>function_name</replaceable>(<replaceable>argument_type</replaceable> [, ...])</term> + <term><literal><replaceable>function_name</replaceable>[(<replaceable>argument_type</replaceable> [, ...])]</literal></term> <listitem> <para> @@ -200,6 +200,8 @@ SELECT CAST ( 2 AS numeric ) + 4.0; be schema-qualified. If it is not, the function will be looked up in the schema search path. The function's result data type must match the target type of the cast. Its arguments are discussed below. + If no argument list is specified, the function name must be unique in + its schema. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/create_collation.sgml b/doc/src/sgml/ref/create_collation.sgml index d757cdfb43..47de9a09b6 100644 --- a/doc/src/sgml/ref/create_collation.sgml +++ b/doc/src/sgml/ref/create_collation.sgml @@ -18,12 +18,14 @@ <refsynopsisdiv> <synopsis> -CREATE COLLATION <replaceable>name</replaceable> ( +CREATE COLLATION [ IF NOT EXISTS ] <replaceable>name</replaceable> ( [ LOCALE = <replaceable>locale</replaceable>, ] [ LC_COLLATE = <replaceable>lc_collate</replaceable>, ] - [ LC_CTYPE = <replaceable>lc_ctype</replaceable> ] + [ LC_CTYPE = <replaceable>lc_ctype</replaceable>, ] + [ PROVIDER = <replaceable>provider</replaceable>, ] + [ VERSION = <replaceable>version</replaceable> ] ) -CREATE COLLATION <replaceable>name</replaceable> FROM <replaceable>existing_collation</replaceable> +CREATE COLLATION [ IF NOT EXISTS ] <replaceable>name</replaceable> FROM <replaceable>existing_collation</replaceable> </synopsis> </refsynopsisdiv> @@ -48,6 +50,17 @@ CREATE COLLATION <replaceable>name</replaceable> FROM <replaceable>existing_coll <variablelist> <varlistentry> + <term><literal>IF NOT EXISTS</literal></term> + <listitem> + <para> + Do not throw an error if a collation with the same name already exists. + A notice is issued in this case. Note that there is no guarantee that + the existing collation is anything like the one that would have been created. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><replaceable>name</replaceable></term> <listitem> @@ -103,6 +116,39 @@ CREATE COLLATION <replaceable>name</replaceable> FROM <replaceable>existing_coll </varlistentry> <varlistentry> + <term><replaceable>provider</replaceable></term> + + <listitem> + <para> + Specifies the provider to use for locale services associated with this + collation. Possible values + are: <literal>icu</literal>,<indexterm><primary>ICU</></> <literal>libc</literal>. + The available choices depend on the operating system and build options. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>version</replaceable></term> + + <listitem> + <para> + Specifies the version string to store with the collation. Normally, + this should be omitted, which will cause the version to be computed + from the actual version of the collation as provided by the operating + system. This option is intended to be used + by <command>pg_upgrade</command> for copying the version from an + existing installation. + </para> + + <para> + See also <xref linkend="sql-altercollation"> for how to handle + collation version mismatches. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><replaceable>existing_collation</replaceable></term> <listitem> diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml index f3a78fe003..3ca9f67263 100644 --- a/doc/src/sgml/ref/create_database.sgml +++ b/doc/src/sgml/ref/create_database.sgml @@ -265,7 +265,8 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable> The <literal>CONNECTION LIMIT</> option is only enforced approximately; if two new sessions start at about the same time when just one connection <quote>slot</> remains for the database, it is possible that - both will fail. Also, the limit is not enforced against superusers. + both will fail. Also, the limit is not enforced against superusers or + background worker processes. </para> </refsect1> @@ -290,17 +291,33 @@ CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace; </para> <para> - To create a database <literal>music</> which supports the ISO-8859-1 - character set: + To create a database <literal>music</> with a different locale: +<programlisting> +CREATE DATABASE music + LC_COLLATE 'sv_SE.utf8' LC_CTYPE 'sv_SE.utf8' + TEMPLATE template0; +</programlisting> + In this example, the <literal>TEMPLATE template0</> clause is required if + the specified locale is different from the one in <literal>template1</>. + (If it is not, then specifying the locale explicitly is redundant.) + </para> + <para> + To create a database <literal>music2</> with a different locale and a + different character set encoding: <programlisting> -CREATE DATABASE music ENCODING 'LATIN1' TEMPLATE template0; +CREATE DATABASE music2 + LC_COLLATE 'sv_SE.iso885915' LC_CTYPE 'sv_SE.iso885915' + ENCODING LATIN9 + TEMPLATE template0; </programlisting> + The specified locale and encoding settings must match, or an error will be + reported. + </para> - In this example, the <literal>TEMPLATE template0</> clause would only - be required if <literal>template1</>'s encoding is not ISO-8859-1. - Note that changing encoding might require selecting new - <literal>LC_COLLATE</> and <literal>LC_CTYPE</> settings as well. + <para> + Note that locale names are specific to the operating system, so that the + above commands might not work in the same way everywhere. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_extension.sgml b/doc/src/sgml/ref/create_extension.sgml index 007d8c9330..14e910115a 100644 --- a/doc/src/sgml/ref/create_extension.sgml +++ b/doc/src/sgml/ref/create_extension.sgml @@ -95,35 +95,21 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name If not specified, and the extension's control file does not specify a schema either, the current default object creation schema is used. </para> + <para> - If the extension specifies <literal>schema</> in its control file, - the schema cannot be overridden with <literal>SCHEMA</> clause. - The <literal>SCHEMA</> clause in this case works as follows: - <itemizedlist> - <listitem> - <para> - If <replaceable class="parameter">schema_name</replaceable> matches - the schema in control file, it will be used normally as there is no - conflict. - </para> - </listitem> - <listitem> - <para> - If the <literal>CASCADE</> clause is given, the - <replaceable class="parameter">schema_name</replaceable> will only - be used for the missing required extensions which do not specify - <literal>schema</> in their control files. - </para> - </listitem> - <listitem> - <para> - If <replaceable class="parameter">schema_name</replaceable> is not - the same as the one in extension's control file and the - <literal>CASCADE</> clause is not given, error will be thrown. - </para> - </listitem> - </itemizedlist> + If the extension specifies a <literal>schema</> parameter in its + control file, then that schema cannot be overridden with + a <literal>SCHEMA</> clause. Normally, an error will be raised if + a <literal>SCHEMA</> clause is given and it conflicts with the + extension's <literal>schema</> parameter. However, if + the <literal>CASCADE</> clause is also given, + then <replaceable class="parameter">schema_name</replaceable> is + ignored when it conflicts. The + given <replaceable class="parameter">schema_name</replaceable> will be + used for installation of any needed extensions that do not + specify <literal>schema</> in their control files. </para> + <para> Remember that the extension itself is not considered to be within any schema: extensions have unqualified names that must be unique @@ -147,7 +133,8 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name <varlistentry> <term><replaceable class="parameter">old_version</replaceable></term> <listitem> - <para><literal>FROM</> <replaceable class="parameter">old_version</> + <para> + <literal>FROM</> <replaceable class="parameter">old_version</> must be specified when, and only when, you are attempting to install an extension that replaces an <quote>old style</> module that is just a collection of objects not packaged into an extension. This option @@ -174,10 +161,13 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name <term><literal>CASCADE</></term> <listitem> <para> - Try to install extension including the required dependencies - recursively. The <literal>SCHEMA</> option will be propagated - to the required extensions. Other options are not recursively - applied when using this clause. + Automatically install any extensions that this extension depends on + that are not already installed. Their dependencies are likewise + automatically installed, recursively. The <literal>SCHEMA</> clause, + if given, applies to all extensions that get installed this way. + Other options of the statement are not applied to + automatically-installed extensions; in particular, their default + versions are always selected. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/create_foreign_table.sgml b/doc/src/sgml/ref/create_foreign_table.sgml index 413b033cb5..065c982082 100644 --- a/doc/src/sgml/ref/create_foreign_table.sgml +++ b/doc/src/sgml/ref/create_foreign_table.sgml @@ -27,6 +27,15 @@ CREATE FOREIGN TABLE [ IF NOT EXISTS ] <replaceable class="PARAMETER">table_name SERVER <replaceable class="parameter">server_name</replaceable> [ OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ... ] ) ] +CREATE FOREIGN TABLE [ IF NOT EXISTS ] <replaceable class="PARAMETER">table_name</replaceable> + PARTITION OF <replaceable class="PARAMETER">parent_table</replaceable> [ ( + { <replaceable class="PARAMETER">column_name</replaceable> [ WITH OPTIONS ] [ <replaceable class="PARAMETER">column_constraint</replaceable> [ ... ] ] + | <replaceable>table_constraint</replaceable> } + [, ... ] +) ] <replaceable class="PARAMETER">partition_bound_spec</replaceable> + SERVER <replaceable class="parameter">server_name</replaceable> +[ OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ... ] ) ] + <phrase>where <replaceable class="PARAMETER">column_constraint</replaceable> is:</phrase> [ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ] @@ -68,6 +77,12 @@ CHECK ( <replaceable class="PARAMETER">expression</replaceable> ) [ NO INHERIT ] </para> <para> + If <literal>PARTITION OF</literal> clause is specified then the table is + created as a partition of <literal>parent_table</literal> with specified + bounds. + </para> + + <para> To be able to create a foreign table, you must have <literal>USAGE</literal> privilege on the foreign server, as well as <literal>USAGE</literal> privilege on all column types used in the table. @@ -314,6 +329,17 @@ CREATE FOREIGN TABLE films ( SERVER film_server; </programlisting></para> + <para> + Create foreign table <structname>measurement_y2016m07</>, which will be + accessed through the server <structname>server_07</>, as a partition + of the range partitioned table <structname>measurement</>: + +<programlisting> +CREATE FOREIGN TABLE measurement_y2016m07 + PARTITION OF measurement FOR VALUES FROM ('2016-07-01') TO ('2016-08-01') + SERVER server_07; +</programlisting></para> + </refsect1> <refsect1 id="SQL-CREATEFOREIGNTABLE-compatibility"> diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml index ac2a5a5f48..4868317a12 100644 --- a/doc/src/sgml/ref/create_function.sgml +++ b/doc/src/sgml/ref/create_function.sgml @@ -188,8 +188,8 @@ CREATE [ OR REPLACE ] FUNCTION </para> <para> Depending on the implementation language it might also be allowed - to specify <quote>pseudotypes</> such as <type>cstring</>. - Pseudotypes indicate that the actual argument type is either + to specify <quote>pseudo-types</> such as <type>cstring</>. + Pseudo-types indicate that the actual argument type is either incompletely specified, or outside the set of ordinary SQL data types. </para> <para> @@ -227,7 +227,7 @@ CREATE [ OR REPLACE ] FUNCTION can be a base, composite, or domain type, or can reference the type of a table column. Depending on the implementation language it might also be allowed - to specify <quote>pseudotypes</> such as <type>cstring</>. + to specify <quote>pseudo-types</> such as <type>cstring</>. If the function is not supposed to return a value, specify <type>void</> as the return type. </para> @@ -429,7 +429,7 @@ CREATE [ OR REPLACE ] FUNCTION is to be executed with the privileges of the user that calls it. That is the default. <literal>SECURITY DEFINER</literal> specifies that the function is to be executed with the - privileges of the user that created it. + privileges of the user that owns it. </para> <para> @@ -780,7 +780,7 @@ SELECT * FROM dup(42); <para> Because a <literal>SECURITY DEFINER</literal> function is executed - with the privileges of the user that created it, care is needed to + with the privileges of the user that owns it, care is needed to ensure that the function cannot be misused. For security, <xref linkend="guc-search-path"> should be set to exclude any schemas writable by untrusted users. This prevents @@ -880,7 +880,6 @@ COMMIT; <member><xref linkend="sql-grant"></member> <member><xref linkend="sql-load"></member> <member><xref linkend="sql-revoke"></member> - <member><xref linkend="app-createlang"></member> </simplelist> </refsect1> diff --git a/doc/src/sgml/ref/create_group.sgml b/doc/src/sgml/ref/create_group.sgml index 1d5cc9b596..158617cb93 100644 --- a/doc/src/sgml/ref/create_group.sgml +++ b/doc/src/sgml/ref/create_group.sgml @@ -30,7 +30,7 @@ CREATE GROUP <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <repla | CREATEROLE | NOCREATEROLE | INHERIT | NOINHERIT | LOGIN | NOLOGIN - | [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>' + | [ ENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>' | VALID UNTIL '<replaceable class="PARAMETER">timestamp</replaceable>' | IN ROLE <replaceable class="PARAMETER">role_name</replaceable> [, ...] | IN GROUP <replaceable class="PARAMETER">role_name</replaceable> [, ...] diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml index 22033e67d7..6e59d73a54 100644 --- a/doc/src/sgml/ref/create_index.sgml +++ b/doc/src/sgml/ref/create_index.sgml @@ -386,7 +386,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= </variablelist> <para> - <acronym>BRIN</> indexes accept a different parameter: + <acronym>BRIN</> indexes accept different parameters: </para> <variablelist> @@ -400,6 +400,16 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= </para> </listitem> </varlistentry> + + <varlistentry> + <term><literal>autosummarize</></term> + <listitem> + <para> + Defines whether a summarization run is invoked for the previous page + range whenever an insertion is detected on the next one. + </para> + </listitem> + </varlistentry> </variablelist> </refsect2> @@ -463,9 +473,9 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <programlisting> postgres=# \d tab Table "public.tab" - Column | Type | Modifiers ---------+---------+----------- - col | integer | + Column | Type | Collation | Nullable | Default +--------+---------+-----------+----------+--------- + col | integer | | | Indexes: "idx" btree (col) INVALID </programlisting> @@ -514,19 +524,6 @@ Indexes: they can be useful. </para> - <caution> - <para> - Hash index operations are not presently WAL-logged, - so hash indexes might need to be rebuilt with <command>REINDEX</> - after a database crash if there were unwritten changes. - Also, changes to hash indexes are not replicated over streaming or - file-based replication after the initial base backup, so they - give wrong answers to queries that subsequently use them. - Hash indexes are also not properly restored during point-in-time - recovery. For these reasons, hash index use is presently discouraged. - </para> - </caution> - <para> Currently, only the B-tree, GiST, GIN, and BRIN index methods support multicolumn indexes. Up to 32 fields can be specified by default. diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml index 41da16d977..75165b677f 100644 --- a/doc/src/sgml/ref/create_language.sgml +++ b/doc/src/sgml/ref/create_language.sgml @@ -230,21 +230,14 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa <title>Notes</title> <para> - The <xref linkend="app-createlang"> program is a simple wrapper around - the <command>CREATE LANGUAGE</> command. It eases - installation of procedural languages from the shell command line. - </para> - - <para> - Use <xref linkend="sql-droplanguage">, or better yet the <xref - linkend="app-droplang"> program, to drop procedural languages. + Use <xref linkend="sql-droplanguage"> to drop procedural languages. </para> <para> The system catalog <classname>pg_language</classname> (see <xref linkend="catalog-pg-language">) records information about the - currently installed languages. Also, <command>createlang</command> - has an option to list the installed languages. + currently installed languages. Also, the <application>psql</application> + command <command>\dL</command> lists the installed languages. </para> <para> @@ -325,8 +318,6 @@ CREATE LANGUAGE plsample <member><xref linkend="sql-droplanguage"></member> <member><xref linkend="sql-grant"></member> <member><xref linkend="sql-revoke"></member> - <member><xref linkend="app-createlang"></member> - <member><xref linkend="app-droplang"></member> </simplelist> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/create_opclass.sgml b/doc/src/sgml/ref/create_opclass.sgml index 7b9d55d38d..829d8f2fff 100644 --- a/doc/src/sgml/ref/create_opclass.sgml +++ b/doc/src/sgml/ref/create_opclass.sgml @@ -235,6 +235,11 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL (currently GiST, GIN and BRIN) allow it to be different. The <literal>STORAGE</> clause must be omitted unless the index method allows a different type to be used. + If the column <replaceable class="parameter">data_type</> is specified + as <type>anyarray</>, the <replaceable class="parameter">storage_type</> + can be declared as <type>anyelement</> to indicate that the index + entries are members of the element type belonging to the actual array + type that each particular index is created for. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/create_policy.sgml b/doc/src/sgml/ref/create_policy.sgml index 89d27879b1..3b24e5e95e 100644 --- a/doc/src/sgml/ref/create_policy.sgml +++ b/doc/src/sgml/ref/create_policy.sgml @@ -22,6 +22,7 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable class="parameter">table_name</replaceable> + [ AS { PERMISSIVE | RESTRICTIVE } ] [ FOR { ALL | SELECT | INSERT | UPDATE | DELETE } ] [ TO { <replaceable class="parameter">role_name</replaceable> | PUBLIC | CURRENT_USER | SESSION_USER } [, ...] ] [ USING ( <replaceable class="parameter">using_expression</replaceable> ) ] @@ -120,6 +121,33 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable </varlistentry> <varlistentry> + <term><literal>PERMISSIVE</literal></term> + <listitem> + <para> + Specify that the policy is to be created as a permissive policy. + All permissive policies which are applicable to a given query will + be combined together using the boolean "OR" operator. By creating + permissive policies, administrators can add to the set of records + which can be accessed. Policies are permissive by default. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICTIVE</literal></term> + <listitem> + <para> + Specify that the policy is to be created as a restrictive policy. + All restrictive policies which are applicable to a given query will + be combined together using the boolean "AND" operator. By creating + restrictive policies, administrators can reduce the set of records + which can be accessed as all restrictive policies must be passed for + each record. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><replaceable class="parameter">command</replaceable></term> <listitem> <para> @@ -391,6 +419,16 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable </para> <para> + Note that there needs to be at least one permissive policy to grant + access to records before restrictive policies can be usefully used to + reduce that access. If only restrictive policies exist, then no records + will be accessible. When a mix of permissive and restrictive policies + are present, a record is only accessible if at least one of the + permissive policies passes, in addition to all the restrictive + policies. + </para> + + <para> Generally, the system will enforce filter conditions imposed using security policies prior to qualifications that appear in user queries, in order to prevent inadvertent exposure of the protected data to diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml new file mode 100644 index 0000000000..48be476374 --- /dev/null +++ b/doc/src/sgml/ref/create_publication.sgml @@ -0,0 +1,215 @@ +<!-- +doc/src/sgml/ref/create_publication.sgml +PostgreSQL documentation +--> + +<refentry id="SQL-CREATEPUBLICATION"> + <indexterm zone="sql-createpublication"> + <primary>CREATE PUBLICATION</primary> + </indexterm> + + <refmeta> + <refentrytitle>CREATE PUBLICATION</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>CREATE PUBLICATION</refname> + <refpurpose>define a new publication</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +CREATE PUBLICATION <replaceable class="parameter">name</replaceable> + [ FOR TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ...] + | FOR ALL TABLES ] + [ WITH ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ] + +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>CREATE PUBLICATION</command> adds a new publication + into the current database. The publication name must be distinct from + the name of any existing publication in the current database. + </para> + + <para> + A publication is essentially a group of tables whose data changes are + intended to be replicated through logical replication. See + <xref linkend="logical-replication-publication"> for details about how + publications fit into the logical replication setup. + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">name</replaceable></term> + <listitem> + <para> + The name of the new publication. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>FOR TABLE</literal></term> + <listitem> + <para> + Specifies a list of tables to add to the publication. If + <literal>ONLY</> is specified before the table name, only + that table is added to the publication. If <literal>ONLY</> is not + specified, the table and all its descendant tables (if any) are added. + Optionally, <literal>*</> can be specified after the table name to + explicitly indicate that descendant tables are included. + </para> + + <para> + Only persistent base tables can be part of a publication. Temporary + tables, unlogged tables, foreign tables, materialized views, regular + views, and partitioned tables cannot be part of a publication. To + replicate a partitioned table, add the individual partitions to the + publication. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>FOR ALL TABLES</literal></term> + <listitem> + <para> + Marks the publication as one that replicates changes for all tables in + the database, including tables created in the future. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>WITH ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term> + <listitem> + <para> + This clause specifies optional parameters for a publication. The + following parameters are supported: + + <variablelist> + <varlistentry> + <term><literal>publish</literal> (<type>string</type>)</term> + <listitem> + <para> + This parameter determines which DML operations will be published by + the new publication to the subscribers. The value is + comma-separated list of operations. The allowed operations are + <literal>insert</literal>, <literal>update</literal>, and + <literal>delete</literal>. The default is to publish all actions, + and so the default value for this option is + <literal>'insert, update, delete'</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + + </para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para> + If neither <literal>FOR TABLE</literal> nor <literal>FOR ALL + TABLES</literal> is specified, then the publication starts out with an + empty set of tables. That is useful if tables are to be added later. + </para> + + <para> + The creation of a publication does not start replication. It only defines + a grouping and filtering logic for future subscribers. + </para> + + <para> + To create a publication, the invoking user must have the + <literal>CREATE</> privilege for the current database. + (Of course, superusers bypass this check.) + </para> + + <para> + To add a table to a publication, the invoking user must have ownership + rights on the table. The <command>FOR ALL TABLES</command> clause requires + the invoking user to be a superuser. + </para> + + <para> + The tables added to a publication that publishes <command>UPDATE</command> + and/or <command>DELETE</command> operations must have + <literal>REPLICA IDENTITY</> defined. Otherwise those operations will be + disallowed on those tables. + </para> + + <para> + For an <command>INSERT ... ON CONFLICT</> command, the publication will + publish the operation that actually results from the command. So depending + of the outcome, it may be published as either <command>INSERT</command> or + <command>UPDATE</command>, or it may not be published at all. + </para> + + <para> + <command>TRUNCATE</command> and <acronym>DDL</acronym> operations + are not published. + </para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para> + Create a publication that publishes all changes in two tables: +<programlisting> +CREATE PUBLICATION mypublication FOR TABLE users, departments; +</programlisting> + </para> + + <para> + Create a publication that publishes all changes in all tables: +<programlisting> +CREATE PUBLICATION alltables FOR ALL TABLES; +</programlisting> + </para> + + <para> + Create a publication that only publishes <command>INSERT</command> + operations in one table: +<programlisting> +CREATE PUBLICATION insert_only FOR TABLE mydata + WITH (publish = 'insert'); +</programlisting> + </para> + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + <command>CREATE PUBLICATION</command> is a <productname>PostgreSQL</> + extension. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-alterpublication"></member> + <member><xref linkend="sql-droppublication"></member> + </simplelist> + </refsect1> +</refentry> diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml index 38cd4c8369..43f2303b48 100644 --- a/doc/src/sgml/ref/create_role.sgml +++ b/doc/src/sgml/ref/create_role.sgml @@ -33,7 +33,7 @@ CREATE ROLE <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replac | REPLICATION | NOREPLICATION | BYPASSRLS | NOBYPASSRLS | CONNECTION LIMIT <replaceable class="PARAMETER">connlimit</replaceable> - | [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>' + | [ ENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>' | VALID UNTIL '<replaceable class="PARAMETER">timestamp</replaceable>' | IN ROLE <replaceable class="PARAMETER">role_name</replaceable> [, ...] | IN GROUP <replaceable class="PARAMETER">role_name</replaceable> [, ...] @@ -198,13 +198,16 @@ CREATE ROLE <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replac <listitem> <para> If role can log in, this specifies how many concurrent connections - the role can make. -1 (the default) means no limit. + the role can make. -1 (the default) means no limit. Note that only + normal connections are counted towards this limit. Neither prepared + transactions nor background worker connections are counted towards + this limit. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>PASSWORD</> <replaceable class="parameter">password</replaceable></term> + <term>[ <literal>ENCRYPTED</> ] <literal>PASSWORD</> <replaceable class="parameter">password</replaceable></term> <listitem> <para> Sets the role's password. (A password is only of use for @@ -216,30 +219,17 @@ CREATE ROLE <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replac user. A null password can optionally be written explicitly as <literal>PASSWORD NULL</literal>. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>ENCRYPTED</></term> - <term><literal>UNENCRYPTED</></term> - <listitem> - <para> - These key words control whether the password is stored - encrypted in the system catalogs. (If neither is specified, - the default behavior is determined by the configuration - parameter <xref linkend="guc-password-encryption">.) If the - presented password string is already in MD5-encrypted format, - then it is stored encrypted as-is, regardless of whether - <literal>ENCRYPTED</> or <literal>UNENCRYPTED</> is specified - (since the system cannot decrypt the specified encrypted - password string). This allows reloading of encrypted - passwords during dump/restore. - </para> - <para> - Note that older clients might lack support for the MD5 - authentication mechanism that is needed to work with passwords - that are stored encrypted. + The password is always stored encrypted in the system catalogs. The + <literal>ENCRYPTED</> keyword has no effect, but is accepted for + backwards compatibility. The method of encryption is determined + by the configuration parameter <xref linkend="guc-password-encryption">. + If the presented password string is already in MD5-encrypted or + SCRAM-encrypted format, then it is stored as-is regardless of + <varname>password_encryption</> (since the system cannot decrypt + the specified encrypted password string, to encrypt it in a + different format). This allows reloading of encrypted passwords + during dump/restore. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml index c9591462ee..f1448e7ab3 100644 --- a/doc/src/sgml/ref/create_sequence.sgml +++ b/doc/src/sgml/ref/create_sequence.sgml @@ -21,7 +21,9 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> -CREATE [ TEMPORARY | TEMP ] SEQUENCE [ IF NOT EXISTS ] <replaceable class="parameter">name</replaceable> [ INCREMENT [ BY ] <replaceable class="parameter">increment</replaceable> ] +CREATE [ TEMPORARY | TEMP ] SEQUENCE [ IF NOT EXISTS ] <replaceable class="parameter">name</replaceable> + [ AS <replaceable class="parameter">data_type</replaceable> ] + [ INCREMENT [ BY ] <replaceable class="parameter">increment</replaceable> ] [ MINVALUE <replaceable class="parameter">minvalue</replaceable> | NO MINVALUE ] [ MAXVALUE <replaceable class="parameter">maxvalue</replaceable> | NO MAXVALUE ] [ START [ WITH ] <replaceable class="parameter">start</replaceable> ] [ CACHE <replaceable class="parameter">cache</replaceable> ] [ [ NO ] CYCLE ] [ OWNED BY { <replaceable class="parameter">table_name</replaceable>.<replaceable class="parameter">column_name</replaceable> | NONE } ] @@ -111,6 +113,21 @@ SELECT * FROM <replaceable>name</replaceable>; </varlistentry> <varlistentry> + <term><replaceable class="parameter">data_type</replaceable></term> + <listitem> + <para> + The optional + clause <literal>AS <replaceable class="parameter">data_type</replaceable></literal> + specifies the data type of the sequence. Valid types are + are <literal>smallint</literal>, <literal>integer</literal>, + and <literal>bigint</literal>. <literal>bigint</literal> is the + default. The data type determines the default minimum and maximum + values of the sequence. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><replaceable class="parameter">increment</replaceable></term> <listitem> <para> @@ -132,9 +149,8 @@ SELECT * FROM <replaceable>name</replaceable>; class="parameter">minvalue</replaceable></literal> determines the minimum value a sequence can generate. If this clause is not supplied or <option>NO MINVALUE</option> is specified, then - defaults will be used. The defaults are 1 and - -2<superscript>63</>-1 for ascending and descending sequences, - respectively. + defaults will be used. The default for an ascending sequence is 1. The + default for a descending sequence is the minimum value of the data type. </para> </listitem> </varlistentry> @@ -148,9 +164,9 @@ SELECT * FROM <replaceable>name</replaceable>; class="parameter">maxvalue</replaceable></literal> determines the maximum value for the sequence. If this clause is not supplied or <option>NO MAXVALUE</option> is specified, then - default values will be used. The defaults are - 2<superscript>63</>-1 and -1 for ascending and descending - sequences, respectively. + default values will be used. The default for an ascending sequence is + the maximum value of the data type. The default for a descending + sequence is -1. </para> </listitem> </varlistentry> @@ -349,12 +365,6 @@ END; <itemizedlist> <listitem> <para> - The standard's <literal>AS <data type></literal> expression is not - supported. - </para> - </listitem> - <listitem> - <para> Obtaining the next value is done using the <function>nextval()</> function instead of the standard's <command>NEXT VALUE FOR</command> expression. diff --git a/doc/src/sgml/ref/create_server.sgml b/doc/src/sgml/ref/create_server.sgml index 2a2f2b6adb..f469df17f3 100644 --- a/doc/src/sgml/ref/create_server.sgml +++ b/doc/src/sgml/ref/create_server.sgml @@ -21,7 +21,7 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> -CREATE SERVER <replaceable class="parameter">server_name</replaceable> [ TYPE '<replaceable class="parameter">server_type</replaceable>' ] [ VERSION '<replaceable class="parameter">server_version</replaceable>' ] +CREATE SERVER [IF NOT EXISTS] <replaceable class="parameter">server_name</replaceable> [ TYPE '<replaceable class="parameter">server_type</replaceable>' ] [ VERSION '<replaceable class="parameter">server_version</replaceable>' ] FOREIGN DATA WRAPPER <replaceable class="parameter">fdw_name</replaceable> [ OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ... ] ) ] </synopsis> @@ -60,6 +60,18 @@ CREATE SERVER <replaceable class="parameter">server_name</replaceable> [ TYPE '< <title>Parameters</title> <variablelist> + <varlistentry> + <term><literal>IF NOT EXISTS</></term> + <listitem> + <para> + Do not throw an error if a server with the same name already exists. + A notice is issued in this case. Note that there is no guarantee that + the existing server is anything like the one that would have been + created. + </para> + </listitem> + </varlistentry> + <varlistentry> <term><replaceable class="parameter">server_name</replaceable></term> <listitem> diff --git a/doc/src/sgml/ref/create_statistics.sgml b/doc/src/sgml/ref/create_statistics.sgml new file mode 100644 index 0000000000..f319a6ea9c --- /dev/null +++ b/doc/src/sgml/ref/create_statistics.sgml @@ -0,0 +1,185 @@ +<!-- +doc/src/sgml/ref/create_statistics.sgml +PostgreSQL documentation +--> + +<refentry id="SQL-CREATESTATISTICS"> + <indexterm zone="sql-createstatistics"> + <primary>CREATE STATISTICS</primary> + </indexterm> + + <refmeta> + <refentrytitle>CREATE STATISTICS</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>CREATE STATISTICS</refname> + <refpurpose>define extended statistics</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +CREATE STATISTICS [ IF NOT EXISTS ] <replaceable class="PARAMETER">statistics_name</replaceable> + [ ( <replaceable class="PARAMETER">statistic_type</replaceable> [, ... ] ) ] + ON <replaceable class="PARAMETER">column_name</replaceable>, <replaceable class="PARAMETER">column_name</replaceable> [, ...] + FROM <replaceable class="PARAMETER">table_name</replaceable> +</synopsis> + + </refsynopsisdiv> + + <refsect1 id="SQL-CREATESTATISTICS-description"> + <title>Description</title> + + <para> + <command>CREATE STATISTICS</command> will create a new extended statistics + object tracking data about the specified table, foreign table or + materialized view. The statistics object will be created in the current + database and will be owned by the user issuing the command. + </para> + + <para> + If a schema name is given (for example, <literal>CREATE STATISTICS + myschema.mystat ...</>) then the statistics object is created in the + specified schema. Otherwise it is created in the current schema. + The name of the statistics object must be distinct from the name of any + other statistics object in the same schema. + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + + <varlistentry> + <term><literal>IF NOT EXISTS</></term> + <listitem> + <para> + Do not throw an error if a statistics object with the same name already + exists. A notice is issued in this case. Note that only the name of + the statistics object is considered here, not the details of its + definition. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">statistics_name</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of the statistics object to be + created. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">statistic_type</replaceable></term> + <listitem> + <para> + A statistic type to be computed in this statistics object. + Currently supported types are + <literal>ndistinct</literal>, which enables n-distinct statistics, and + <literal>dependencies</literal>, which enables functional + dependency statistics. + If this clause is omitted, all supported statistic types are + included in the statistics object. + For more information, see <xref linkend="planner-stats-extended"> + and <xref linkend="multivariate-statistics-examples">. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">column_name</replaceable></term> + <listitem> + <para> + The name of a table column to be covered by the computed statistics. + At least two column names must be given. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">table_name</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of the table containing the + column(s) the statistics are computed on. + </para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para> + You must be the owner of a table to create a statistics object + reading it. Once created, however, the ownership of the statistics + object is independent of the underlying table(s). + </para> + </refsect1> + + <refsect1 id="SQL-CREATESTATISTICS-examples"> + <title>Examples</title> + + <para> + Create table <structname>t1</> with two functionally dependent columns, i.e. + knowledge of a value in the first column is sufficient for determining the + value in the other column. Then functional dependency statistics are built + on those columns: + +<programlisting> +CREATE TABLE t1 ( + a int, + b int +); + +INSERT INTO t1 SELECT i/100, i/500 + FROM generate_series(1,1000000) s(i); + +ANALYZE t1; + +-- the number of matching rows will be drastically underestimated: +EXPLAIN ANALYZE SELECT * FROM t1 WHERE (a = 1) AND (b = 0); + +CREATE STATISTICS s1 (dependencies) ON a, b FROM t1; + +ANALYZE t1; + +-- now the rowcount estimate is more accurate: +EXPLAIN ANALYZE SELECT * FROM t1 WHERE (a = 1) AND (b = 0); +</programlisting> + + Without functional-dependency statistics, the planner would assume + that the two <literal>WHERE</> conditions are independent, and would + multiply their selectivities together to arrive at a much-too-small + rowcount estimate. + With such statistics, the planner recognizes that the <literal>WHERE</> + conditions are redundant and does not underestimate the rowcount. + </para> + + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + There is no <command>CREATE STATISTICS</command> command in the SQL standard. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-alterstatistics"></member> + <member><xref linkend="sql-dropstatistics"></member> + </simplelist> + </refsect1> +</refentry> diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml new file mode 100644 index 0000000000..2c91eb6f50 --- /dev/null +++ b/doc/src/sgml/ref/create_subscription.sgml @@ -0,0 +1,278 @@ +<!-- +doc/src/sgml/ref/create_subscription.sgml +PostgreSQL documentation +--> + +<refentry id="SQL-CREATESUBSCRIPTION"> + <indexterm zone="sql-createsubscription"> + <primary>CREATE SUBSCRIPTION</primary> + </indexterm> + + <refmeta> + <refentrytitle>CREATE SUBSCRIPTION</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>CREATE SUBSCRIPTION</refname> + <refpurpose>define a new subscription</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +CREATE SUBSCRIPTION <replaceable class="PARAMETER">subscription_name</replaceable> + CONNECTION '<replaceable class="PARAMETER">conninfo</replaceable>' + PUBLICATION <replaceable class="PARAMETER">publication_name</replaceable> [, ...] + [ WITH ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ] +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>CREATE SUBSCRIPTION</command> adds a new subscription for a + current database. The subscription name must be distinct from the name of + any existing subscription in the database. + </para> + + <para> + The subscription represents a replication connection to the publisher. As + such this command does not only add definitions in the local catalogs but + also creates a replication slot on the publisher. + </para> + + <para> + A logical replication worker will be started to replicate data for the new + subscription at the commit of the transaction where this command is run. + </para> + + <para> + <command>CREATE SUBSCRIPTION</command> cannot be executed inside a + transaction block when the parameter <literal>create_slot</literal> is specified. + </para> + + <para> + Additional info about subscriptions and logical replication as a whole + can is available at <xref linkend="logical-replication-subscription"> and + <xref linkend="logical-replication">. + </para> + + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">subscription_name</replaceable></term> + <listitem> + <para> + The name of the new subscription. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term> + <listitem> + <para> + The connection string to the publisher. For details + see <xref linkend="libpq-connstring">. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable></literal></term> + <listitem> + <para> + Names of the publications on the publisher to subscribe to. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>WITH ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term> + <listitem> + <para> + This clause specifies optional parameters for a subscription. The + following parameters are supported: + + <variablelist> + <varlistentry> + <term><literal>copy_data</literal> (<type>boolean</type>)</term> + <listitem> + <para> + Specifies whether the existing data in the publications that are + being subscribed to should be copied once the replication starts. + The default is <literal>true</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>create_slot</literal> (<type>boolean</type>)</term> + <listitem> + <para> + Specifies whether the command should create the replication slot on + the publisher. The default is <literal>true</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>enabled</literal> (<type>boolean</type>)</term> + <listitem> + <para> + Specifies whether the subscription should be actively replicating, + or whether it should be just setup but not started yet. The default + is <literal>true</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>slot_name</literal> (<type>string</type>)</term> + <listitem> + <para> + Name of the replication slot to use. The default behavior is to + use the name of the subscription for the slot name. + </para> + + <para> + When <literal>slot_name</literal> is set to + <literal>NONE</literal>, there will be no replication slot + associated with the subscription. This can be used if the + replication slot will be created later manually. Such + subscriptions must also have both <literal>enabled</literal> and + <literal>create_slot</literal> set to <literal>false</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>synchronous_commit</literal> (<type>enum</type>)</term> + <listitem> + <para> + The value of this parameter overrides the + <xref linkend="guc-synchronous-commit"> setting. The default + value is <literal>off</literal>. + </para> + + <para> + It is safe to use <literal>off</literal> for logical replication: + If the subscriber loses transactions because of missing + synchronization, the data will be resent from the publisher. + </para> + + <para> + A different setting might be appropriate when doing synchronous + logical replication. The logical replication workers report the + positions of writes and flushes to the publisher, and when using + synchronous replication, the publisher will wait for the actual + flush. This means that setting + <literal>synchronous_commit</literal> for the subscriber to + <literal>off</literal> when the subscription is used for + synchronous replication might increase the latency for + <command>COMMIT</command> on the publisher. In this scenario, it + can be advantageous to set <literal>synchronous_commit</literal> + to <literal>local</literal> or higher. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>connect</literal> (<type>boolean</type>)</term> + <listitem> + <para> + Specifies whether the <command>CREATE SUBSCRIPTION</command> + should connect to the publisher at all. Setting this to + <literal>false</literal> will change default values of + <literal>enabled</literal>, <literal>create_slot</literal> and + <literal>copy_data</literal> to <literal>false</literal>. + </para> + + <para> + It is not allowed to combine <literal>connect</literal> set to + <literal>false</literal> and <literal>enabled</literal>, + <literal>create_slot</literal>, or <literal>copy_data</literal> + set to <literal>true</literal>. + </para> + + <para> + Since no connection is made when this option is set + to <literal>false</literal>, the tables are not subscribed, and so + after you enable the subscription nothing will be replicated. + It is required to run + <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</> in order + for tables to be subscribed. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para> + See <xref linkend="streaming-replication-authentication"> for details on + how to configure access control between the subscription and the + publication instance. + </para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para> + Create a subscription to a remote server that replicates tables in + the publications <literal>mypublication</literal> and + <literal>insert_only</literal> and starts replicating immediately on + commit: +<programlisting> +CREATE SUBSCRIPTION mysub + CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb' + PUBLICATION mypublication, insert_only; +</programlisting> + </para> + + <para> + Create a subscription to a remote server that replicates tables in + the <literal>insert_only</literal> publication and does not start replicating + until enabled at a later time. +<programlisting> +CREATE SUBSCRIPTION mysub + CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb' + PUBLICATION insert_only + WITH (enabled = false); +</programlisting> + </para> + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + <command>CREATE SUBSCRIPTION</command> is a <productname>PostgreSQL</> + extension. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-altersubscription"></member> + <member><xref linkend="sql-dropsubscription"></member> + <member><xref linkend="sql-createpublication"></member> + <member><xref linkend="sql-alterpublication"></member> + </simplelist> + </refsect1> +</refentry> diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index 2b842d5fb9..8d1e4ee487 100755 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -28,6 +28,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI [, ... ] ] ) [ INHERITS ( <replaceable>parent_table</replaceable> [, ... ] ) ] +[ PARTITION BY { RANGE | LIST } ( { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ COLLATE <replaceable class="parameter">collation</replaceable> ] [ <replaceable class="parameter">opclass</replaceable> ] [, ... ] ) ] [ WITH ( <replaceable class="PARAMETER">storage_parameter</replaceable> [= <replaceable class="PARAMETER">value</replaceable>] [, ... ] ) | WITH OIDS | WITHOUT OIDS ] [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] [ TABLESPACE <replaceable class="PARAMETER">tablespace_name</replaceable> ] @@ -40,10 +41,22 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] <replaceable class="PARAMETER">table_name</replaceable> OF <replaceable class="PARAMETER">type_name</replaceable> [ ( - { <replaceable class="PARAMETER">column_name</replaceable> WITH OPTIONS [ <replaceable class="PARAMETER">column_constraint</replaceable> [ ... ] ] + { <replaceable class="PARAMETER">column_name</replaceable> [ WITH OPTIONS ] [ <replaceable class="PARAMETER">column_constraint</replaceable> [ ... ] ] | <replaceable>table_constraint</replaceable> } [, ... ] ) ] +[ PARTITION BY { RANGE | LIST } ( { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ COLLATE <replaceable class="parameter">collation</replaceable> ] [ <replaceable class="parameter">opclass</replaceable> ] [, ... ] ) ] +[ WITH ( <replaceable class="PARAMETER">storage_parameter</replaceable> [= <replaceable class="PARAMETER">value</replaceable>] [, ... ] ) | WITH OIDS | WITHOUT OIDS ] +[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] +[ TABLESPACE <replaceable class="PARAMETER">tablespace_name</replaceable> ] + +CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] <replaceable class="PARAMETER">table_name</replaceable> + PARTITION OF <replaceable class="PARAMETER">parent_table</replaceable> [ ( + { <replaceable class="PARAMETER">column_name</replaceable> [ WITH OPTIONS ] [ <replaceable class="PARAMETER">column_constraint</replaceable> [ ... ] ] + | <replaceable>table_constraint</replaceable> } + [, ... ] +) ] FOR VALUES <replaceable class="PARAMETER">partition_bound_spec</replaceable> +[ PARTITION BY { RANGE | LIST } ( { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ COLLATE <replaceable class="parameter">collation</replaceable> ] [ <replaceable class="parameter">opclass</replaceable> ] [, ... ] ) ] [ WITH ( <replaceable class="PARAMETER">storage_parameter</replaceable> [= <replaceable class="PARAMETER">value</replaceable>] [, ... ] ) | WITH OIDS | WITHOUT OIDS ] [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] [ TABLESPACE <replaceable class="PARAMETER">tablespace_name</replaceable> ] @@ -61,6 +74,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI NULL | CHECK ( <replaceable class="PARAMETER">expression</replaceable> ) [ NO INHERIT ] | DEFAULT <replaceable>default_expr</replaceable> | + GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( <replaceable>sequence_options</replaceable> ) ] | UNIQUE <replaceable class="PARAMETER">index_parameters</replaceable> | PRIMARY KEY <replaceable class="PARAMETER">index_parameters</replaceable> | REFERENCES <replaceable class="PARAMETER">reftable</replaceable> [ ( <replaceable class="PARAMETER">refcolumn</replaceable> ) ] [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] @@ -80,7 +94,12 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI <phrase>and <replaceable class="PARAMETER">like_option</replaceable> is:</phrase> -{ INCLUDING | EXCLUDING } { DEFAULTS | CONSTRAINTS | INDEXES | STORAGE | COMMENTS | ALL } +{ INCLUDING | EXCLUDING } { DEFAULTS | CONSTRAINTS | IDENTITY | INDEXES | STORAGE | COMMENTS | ALL } + +<phrase>and <replaceable class="PARAMETER">partition_bound_spec</replaceable> is:</phrase> + +{ IN ( { <replaceable class="PARAMETER">bound_literal</replaceable> | NULL } [, ...] ) | + FROM ( { <replaceable class="PARAMETER">bound_literal</replaceable> | UNBOUNDED } [, ...] ) TO ( { <replaceable class="PARAMETER">bound_literal</replaceable> | UNBOUNDED } [, ...] ) } <phrase><replaceable class="PARAMETER">index_parameters</replaceable> in <literal>UNIQUE</literal>, <literal>PRIMARY KEY</literal>, and <literal>EXCLUDE</literal> constraints are:</phrase> @@ -241,6 +260,90 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI </listitem> </varlistentry> + <varlistentry id="SQL-CREATETABLE-PARTITION"> + <term><literal>PARTITION OF <replaceable class="PARAMETER">parent_table</replaceable> FOR VALUES <replaceable class="PARAMETER">partition_bound_spec</replaceable></literal></term> + <listitem> + <para> + Creates the table as <firstterm>partition</firstterm> of the specified + parent table. + </para> + + <para> + The partition bound specification must correspond to the partitioning + method and partition key of the parent table, and must not overlap with + any existing partition of that parent. + </para> + + <para> + Each of the values specified in the partition bound specification is + a literal, <literal>NULL</literal>, or <literal>UNBOUNDED</literal>. + A literal is either a numeric constant or a string constant that is + coercible to the corresponding partition key column's type. + </para> + + <para> + When creating a range partition, the lower bound specified with + <literal>FROM</literal> is an inclusive bound, whereas the upper + bound specified with <literal>TO</literal> is an exclusive bound. + That is, the values specified in the <literal>FROM</literal> list + are accepted values of the corresponding partition key columns in a + given partition, whereas those in the <literal>TO</literal> list are + not. To be precise, this applies only to the first of the partition + key columns for which the corresponding values in the <literal>FROM</literal> + and <literal>TO</literal> lists are not equal. All rows in a given + partition contain the same values for all preceding columns, equal to + those specified in <literal>FROM</literal> and <literal>TO</literal> + lists. On the other hand, any subsequent columns are insignificant + as far as implicit partition constraint is concerned. + </para> + + <para> + Specifying <literal>UNBOUNDED</literal> in <literal>FROM</literal> + signifies <literal>-infinity</literal> as the lower bound of the + corresponding column, whereas it signifies <literal>+infinity</literal> + as the upper bound when specified in <literal>TO</literal>. + </para> + + <para> + When creating a list partition, <literal>NULL</literal> can be + specified to signify that the partition allows the partition key + column to be null. However, there cannot be more than one such + list partition for a given parent table. <literal>NULL</literal> + cannot be specified for range partitions. + </para> + + <para> + A partition must have the same column names and types as the partitioned + table to which it belongs. If the parent is specified <literal>WITH + OIDS</literal> then all partitions must have OIDs; the parent's OID + column will be inherited by all partitions just like any other column. + Modifications to the column names or types of a partitioned table, or + the addition or removal of an OID column, will automatically propagate + to all partitions. <literal>CHECK</> constraints will be inherited + automatically by every partition, but an individual partition may specify + additional <literal>CHECK</> constraints; additional constraints with + the same name and condition as in the parent will be merged with the + parent constraint. Defaults may be specified separately for each + partition. + </para> + + <para> + Rows inserted into a partitioned table will be automatically routed to + the correct partition. If no suitable partition exists, an error will + occur. Also, if updating a row in a given partition causes it to move + to another partition due to the new partition key, an error will occur. + </para> + + <para> + Operations such as TRUNCATE which normally affect a table and all of its + inheritance children will cascade to all partitions, but may also be + performed on an individual partition. Note that dropping a partition + with <literal>DROP TABLE</literal> requires taking an <literal>ACCESS + EXCLUSIVE</literal> lock on the parent table. + </para> + </listitem> + </varlistentry> + <varlistentry> <term><replaceable class="PARAMETER">column_name</replaceable></term> <listitem> @@ -326,6 +429,47 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI Column <literal>STORAGE</> settings are also copied from parent tables. </para> + <para> + If a column in the parent table is an identity column, that property is + not inherited. A column in the child table can be declared identity + column if desired. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>PARTITION BY { RANGE | LIST } ( { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ <replaceable class="parameter">opclass</replaceable> ] [, ...] ) </literal></term> + <listitem> + <para> + The optional <literal>PARTITION BY</literal> clause specifies a strategy + of partitioning the table. The table thus created is called a + <firstterm>partitioned</firstterm> table. The parenthesized list of + columns or expressions forms the <firstterm>partition key</firstterm> + for the table. When using range partitioning, the partition key can + include multiple columns or expressions (up to 32, but this limit can + altered when building <productname>PostgreSQL</productname>.), but for + list partitioning, the partition key must consist of a single column or + expression. If no btree operator class is specified when creating a + partitioned table, the default btree operator class for the datatype will + be used. If there is none, an error will be reported. + </para> + + <para> + A partitioned table is divided into sub-tables (called partitions), + which are created using separate <literal>CREATE TABLE</> commands. + The partitioned table is itself empty. A data row inserted into the + table is routed to a partition based on the value of columns or + expressions in the partition key. If no existing partition matches + the values in the new row, an error will be reported. + </para> + + <para> + Partitioned tables do not support <literal>UNIQUE</literal>, + <literal>PRIMARY KEY</literal>, <literal>EXCLUDE</literal>, or + <literal>FOREIGN KEY</literal> constraints; however, you can define + these constraints on individual partitions. + </para> + </listitem> </varlistentry> @@ -354,6 +498,12 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI the original and new tables. </para> <para> + Any identity specifications of copied column definitions will only be + copied if <literal>INCLUDING IDENTITY</literal> is specified. A new + sequence is created for each identity column of the new table, separate + from the sequences associated with the old table. + </para> + <para> Not-null constraints are always copied to the new table. <literal>CHECK</literal> constraints will be copied only if <literal>INCLUDING CONSTRAINTS</literal> is specified. @@ -385,7 +535,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI </para> <para> <literal>INCLUDING ALL</literal> is an abbreviated form of - <literal>INCLUDING DEFAULTS INCLUDING CONSTRAINTS INCLUDING INDEXES INCLUDING STORAGE INCLUDING COMMENTS</literal>. + <literal>INCLUDING DEFAULTS INCLUDING IDENTITY INCLUDING CONSTRAINTS INCLUDING INDEXES INCLUDING STORAGE INCLUDING COMMENTS</literal>. </para> <para> Note that unlike <literal>INHERITS</literal>, columns and @@ -500,6 +650,37 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI </varlistentry> <varlistentry> + <term><literal>GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( <replaceable>sequence_options</replaceable> ) ]</literal></term> + <listitem> + <para> + This clause creates the column as an <firstterm>identity + column</firstterm>. It will have an implicit sequence attached to it + and the column in new rows will automatically have values from the + sequence assigned to it. + </para> + + <para> + The clauses <literal>ALWAYS</literal> and <literal>BY DEFAULT</literal> + determine how the sequence value is given precedence over a + user-specified value in an <command>INSERT</command> statement. + If <literal>ALWAYS</literal> is specified, a user-specified value is + only accepted if the <command>INSERT</command> statement + specifies <literal>OVERRIDING SYSTEM VALUE</literal>. If <literal>BY + DEFAULT</literal> is specified, then the user-specified value takes + precedence. See <xref linkend="sql-insert"> for details. (In + the <command>COPY</command> command, user-specified values are always + used regardless of this setting.) + </para> + + <para> + The optional <replaceable>sequence_options</replaceable> clause can be + used to override the options of the sequence. + See <xref linkend="sql-createsequence"> for details. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><literal>UNIQUE</> (column constraint)</term> <term><literal>UNIQUE ( <replaceable class="PARAMETER">column_name</replaceable> [, ... ] )</> (table constraint)</term> @@ -641,9 +822,11 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI class="parameter">refcolumn</replaceable> list is omitted, the primary key of the <replaceable class="parameter">reftable</replaceable> is used. The referenced columns must be the columns of a non-deferrable - unique or primary key constraint in the referenced table. Note that - foreign key constraints cannot be defined between temporary tables and - permanent tables. + unique or primary key constraint in the referenced table. The user + must have <literal>REFERENCES</> permission on the referenced table + (either the whole table, or the specific referenced columns). + Note that foreign key constraints cannot be defined between temporary + tables and permanent tables. </para> <para> @@ -1043,6 +1226,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI If a table parameter value is set and the equivalent <literal>toast.</literal> parameter is not, the TOAST table will use the table's parameter value. + Specifying these parameters for partitioned tables is not supported, + but you may specify them for individual leaf partitions. </para> <variablelist> @@ -1264,7 +1449,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI <para> Using OIDs in new applications is not recommended: where - possible, using a <literal>SERIAL</literal> or other sequence + possible, using an identity column or other sequence generator as the table's primary key is preferred. However, if your application does make use of OIDs to identify specific rows of a table, it is recommended to create a unique constraint @@ -1324,7 +1509,7 @@ CREATE TABLE films ( ); CREATE TABLE distributors ( - did integer PRIMARY KEY DEFAULT nextval('serial'), + did integer PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY, name varchar(40) NOT NULL CHECK (name <> '') ); </programlisting> @@ -1517,6 +1702,88 @@ CREATE TABLE employees OF employee_type ( salary WITH OPTIONS DEFAULT 1000 ); </programlisting></para> + + <para> + Create a range partitioned table: +<programlisting> +CREATE TABLE measurement ( + logdate date not null, + peaktemp int, + unitsales int +) PARTITION BY RANGE (logdate); +</programlisting></para> + + <para> + Create a range partitioned table with multiple columns in the partition key: +<programlisting> +CREATE TABLE measurement_year_month ( + logdate date not null, + peaktemp int, + unitsales int +) PARTITION BY RANGE (EXTRACT(YEAR FROM logdate), EXTRACT(MONTH FROM logdate)); +</programlisting></para> + + <para> + Create a list partitioned table: +<programlisting> +CREATE TABLE cities ( + city_id bigserial not null, + name text not null, + population bigint +) PARTITION BY LIST (left(lower(name), 1)); +</programlisting></para> + + <para> + Create partition of a range partitioned table: +<programlisting> +CREATE TABLE measurement_y2016m07 + PARTITION OF measurement ( + unitsales DEFAULT 0 +) FOR VALUES FROM ('2016-07-01') TO ('2016-08-01'); +</programlisting></para> + + <para> + Create a few partitions of a range partitioned table with multiple + columns in the partition key: +<programlisting> +CREATE TABLE measurement_ym_older + PARTITION OF measurement_year_month + FOR VALUES FROM (unbounded, unbounded) TO (2016, 11); + +CREATE TABLE measurement_ym_y2016m11 + PARTITION OF measurement_year_month + FOR VALUES FROM (2016, 11) TO (2016, 12); + +CREATE TABLE measurement_ym_y2016m12 + PARTITION OF measurement_year_month + FOR VALUES FROM (2016, 12) TO (2017, 01); + +CREATE TABLE measurement_ym_y2017m01 + PARTITION OF measurement_year_month + FOR VALUES FROM (2017, 01) TO (2017, 02); +</programlisting></para> + + <para> + Create partition of a list partitioned table: +<programlisting> +CREATE TABLE cities_ab + PARTITION OF cities ( + CONSTRAINT city_id_nonzero CHECK (city_id != 0) +) FOR VALUES IN ('a', 'b'); +</programlisting></para> + + <para> + Create partition of a list partitioned table that is itself further + partitioned and then add a partition to it: +<programlisting> +CREATE TABLE cities_ab + PARTITION OF cities ( + CONSTRAINT city_id_nonzero CHECK (city_id != 0) +) FOR VALUES IN ('a', 'b') PARTITION BY RANGE (population); + +CREATE TABLE cities_ab_10000_to_100000 + PARTITION OF cities_ab FOR VALUES FROM (10000) TO (100000); +</programlisting></para> </refsect1> <refsect1 id="SQL-CREATETABLE-compatibility"> @@ -1657,6 +1924,20 @@ CREATE TABLE employees OF employee_type ( </refsect2> <refsect2> + <title>Multiple Identity Columns</title> + + <para> + <productname>PostgreSQL</productname> allows a table to have more than one + identity column. The standard specifies that a table can have at most one + identity column. This is relaxed mainly to give more flexibility for + doing schema changes or migrations. Note that + the <command>INSERT</command> command supports only one override clause + that applies to the entire statement, so having multiple identity columns + with different behaviors is not well supported. + </para> + </refsect2> + + <refsect2> <title><literal>LIKE</> Clause</title> <para> @@ -1698,6 +1979,25 @@ CREATE TABLE employees OF employee_type ( effect can be had using the OID feature. </para> </refsect2> + + <refsect2> + <title><literal>PARTITION BY</> Clause</title> + + <para> + The <literal>PARTITION BY</> clause is a + <productname>PostgreSQL</productname> extension. + </para> + </refsect2> + + <refsect2> + <title><literal>PARTITION OF</> Clause</title> + + <para> + The <literal>PARTITION OF</> clause is a + <productname>PostgreSQL</productname> extension. + </para> + </refsect2> + <refsect2> <title><productname>Postgres-XL</> Specifics</title> diff --git a/doc/src/sgml/ref/create_transform.sgml b/doc/src/sgml/ref/create_transform.sgml index f44ee89d33..647c3b9f05 100644 --- a/doc/src/sgml/ref/create_transform.sgml +++ b/doc/src/sgml/ref/create_transform.sgml @@ -19,8 +19,8 @@ <refsynopsisdiv> <synopsis> CREATE [ OR REPLACE ] TRANSFORM FOR <replaceable>type_name</replaceable> LANGUAGE <replaceable>lang_name</replaceable> ( - FROM SQL WITH FUNCTION <replaceable>from_sql_function_name</replaceable> (<replaceable>argument_type</replaceable> [, ...]), - TO SQL WITH FUNCTION <replaceable>to_sql_function_name</replaceable> (<replaceable>argument_type</replaceable> [, ...]) + FROM SQL WITH FUNCTION <replaceable>from_sql_function_name</replaceable> [ (<replaceable>argument_type</replaceable> [, ...]) ], + TO SQL WITH FUNCTION <replaceable>to_sql_function_name</replaceable> [ (<replaceable>argument_type</replaceable> [, ...]) ] ); </synopsis> </refsynopsisdiv> @@ -104,7 +104,7 @@ CREATE [ OR REPLACE ] TRANSFORM FOR <replaceable>type_name</replaceable> LANGUAG </varlistentry> <varlistentry> - <term><replaceable>from_sql_function_name</replaceable>(<replaceable>argument_type</replaceable> [, ...])</term> + <term><literal><replaceable>from_sql_function_name</replaceable>[(<replaceable>argument_type</replaceable> [, ...])]</literal></term> <listitem> <para> @@ -116,12 +116,14 @@ CREATE [ OR REPLACE ] TRANSFORM FOR <replaceable>type_name</replaceable> LANGUAG SQL-level function returning <type>internal</type> without at least one argument of type <type>internal</type>.) The actual return value will be something specific to the language implementation. + If no argument list is specified, the function name must be unique in + its schema. </para> </listitem> </varlistentry> <varlistentry> - <term><replaceable>to_sql_function_name</replaceable>(<replaceable>argument_type</replaceable> [, ...])</term> + <term><literal><replaceable>to_sql_function_name</replaceable>[(<replaceable>argument_type</replaceable> [, ...])]</literal></term> <listitem> <para> @@ -130,6 +132,8 @@ CREATE [ OR REPLACE ] TRANSFORM FOR <replaceable>type_name</replaceable> LANGUAG <type>internal</type> and return the type that is the type for the transform. The actual argument value will be something specific to the language implementation. + If no argument list is specified, the function name must be unique in + its schema. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/create_trigger.sgml b/doc/src/sgml/ref/create_trigger.sgml index 726d9ae8e8..d73eec82cf 100644 --- a/doc/src/sgml/ref/create_trigger.sgml +++ b/doc/src/sgml/ref/create_trigger.sgml @@ -8,6 +8,11 @@ PostgreSQL documentation <primary>CREATE TRIGGER</primary> </indexterm> + <indexterm> + <primary>transition tables</primary> + <seealso>ephemeral named relation</seealso> + </indexterm> + <refmeta> <refentrytitle>CREATE TRIGGER</refentrytitle> <manvolnum>7</manvolnum> @@ -25,6 +30,7 @@ CREATE [ CONSTRAINT ] TRIGGER <replaceable class="PARAMETER">name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> [ FROM <replaceable class="parameter">referenced_table_name</replaceable> ] [ NOT DEFERRABLE | [ DEFERRABLE ] [ INITIALLY IMMEDIATE | INITIALLY DEFERRED ] ] + [ REFERENCING { { OLD | NEW } TABLE [ AS ] <replaceable class="PARAMETER">transition_relation_name</replaceable> } [ ... ] ] [ FOR [ EACH ] { ROW | STATEMENT } ] [ WHEN ( <replaceable class="parameter">condition</replaceable> ) ] EXECUTE PROCEDURE <replaceable class="PARAMETER">function_name</replaceable> ( <replaceable class="PARAMETER">arguments</replaceable> ) @@ -183,6 +189,15 @@ CREATE [ CONSTRAINT ] TRIGGER <replaceable class="PARAMETER">name</replaceable> </para> <para> + The <literal>REFERENCING</> option is only allowed for an <literal>AFTER</> + trigger which is not a constraint trigger. <literal>OLD TABLE</> may only + be specified once, and only on a trigger which can fire on + <literal>UPDATE</> or <literal>DELETE</>. <literal>NEW TABLE</> may only + be specified once, and only on a trigger which can fire on + <literal>UPDATE</> or <literal>INSERT</>. + </para> + + <para> <command>SELECT</command> does not modify any rows so you cannot create <command>SELECT</command> triggers. Rules and views are more appropriate in such cases. @@ -287,6 +302,40 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ </varlistentry> <varlistentry> + <term><literal>REFERENCING</literal></term> + <listitem> + <para> + This immediately precedes the declaration of one or two relations which + can be used to read the before and/or after images of all rows directly + affected by the triggering statement. An <literal>AFTER EACH ROW</> + trigger is allowed to use both these transition relation names and the + row names (<literal>OLD</> and <literal>NEW</>) which reference each + individual row for which the trigger fires. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>OLD TABLE</literal></term> + <term><literal>NEW TABLE</literal></term> + <listitem> + <para> + This specifies whether the named relation contains the before or after + images for rows affected by the statement which fired the trigger. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">transition_relation_name</replaceable></term> + <listitem> + <para> + The (unqualified) name to be used within the trigger for this relation. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><literal>FOR EACH ROW</literal></term> <term><literal>FOR EACH STATEMENT</literal></term> @@ -479,6 +528,30 @@ CREATE TRIGGER view_insert FOR EACH ROW EXECUTE PROCEDURE view_insert_row(); </programlisting> + + Execute the function <function>check_transfer_balances_to_zero</> for each + statement to confirm that the <literal>transfer</> rows offset to a net of + zero: + +<programlisting> +CREATE TRIGGER transfer_insert + AFTER INSERT ON transfer + REFERENCING NEW TABLE AS inserted + FOR EACH STATEMENT + EXECUTE PROCEDURE check_transfer_balances_to_zero(); +</programlisting> + + Execute the function <function>check_matching_pairs</> for each row to + confirm that changes are made to matching pairs at the same time (by the + same statement): + +<programlisting> +CREATE TRIGGER paired_items_update + AFTER UPDATE ON paired_items + REFERENCING NEW TABLE AS newtab OLD TABLE AS oldtab + FOR EACH ROW + EXECUTE PROCEDURE check_matching_pairs(); +</programlisting> </para> <para> @@ -507,24 +580,14 @@ CREATE TRIGGER view_insert <itemizedlist> <listitem> <para> - SQL allows you to define aliases for the <quote>old</quote> - and <quote>new</quote> rows or tables for use in the definition - of the triggered action (e.g., <literal>CREATE TRIGGER ... ON - tablename REFERENCING OLD ROW AS somename NEW ROW AS othername - ...</literal>). Since <productname>PostgreSQL</productname> - allows trigger procedures to be written in any number of - user-defined languages, access to the data is handled in a - language-specific way. - </para> - </listitem> - - <listitem> - <para> - <productname>PostgreSQL</productname> does not allow the old and new - tables to be referenced in statement-level triggers, i.e., the tables - that contain all the old and/or new rows, which are referred to by the - <literal>OLD TABLE</literal> and <literal>NEW TABLE</literal> clauses in - the <acronym>SQL</> standard. + While transition tables for <literal>AFTER</> triggers are specified + using the <literal>REFERENCING</> clause in the standard way, the row + variables used in <literal>FOR EACH ROW</> triggers may not be + specified in <literal>REFERENCING</> clause. They are available in a + manner which is dependent on the language in which the trigger function + is written. Some languages effectively behave as though there is a + <literal>REFERENCING</> clause containing <literal>OLD ROW AS OLD NEW + ROW AS NEW</>. </para> </listitem> diff --git a/doc/src/sgml/ref/create_type.sgml b/doc/src/sgml/ref/create_type.sgml index 5a09f1942a..7146c4a27b 100644 --- a/doc/src/sgml/ref/create_type.sgml +++ b/doc/src/sgml/ref/create_type.sgml @@ -824,7 +824,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> In <productname>PostgreSQL</productname> versions before 7.3, it was customary to avoid creating a shell type at all, by replacing the functions' forward references to the type name with the placeholder - pseudotype <type>opaque</>. The <type>cstring</> arguments and + pseudo-type <type>opaque</>. The <type>cstring</> arguments and results also had to be declared as <type>opaque</> before 7.3. To support loading of old dump files, <command>CREATE TYPE</> will accept I/O functions declared using <type>opaque</>, but it will issue diff --git a/doc/src/sgml/ref/create_user.sgml b/doc/src/sgml/ref/create_user.sgml index 574604f796..8a596eec9f 100644 --- a/doc/src/sgml/ref/create_user.sgml +++ b/doc/src/sgml/ref/create_user.sgml @@ -33,7 +33,7 @@ CREATE USER <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replac | REPLICATION | NOREPLICATION | BYPASSRLS | NOBYPASSRLS | CONNECTION LIMIT <replaceable class="PARAMETER">connlimit</replaceable> - | [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>' + | [ ENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>' | VALID UNTIL '<replaceable class="PARAMETER">timestamp</replaceable>' | IN ROLE <replaceable class="PARAMETER">role_name</replaceable> [, ...] | IN GROUP <replaceable class="PARAMETER">role_name</replaceable> [, ...] diff --git a/doc/src/sgml/ref/create_user_mapping.sgml b/doc/src/sgml/ref/create_user_mapping.sgml index 30636b2a5a..8e406f22e2 100644 --- a/doc/src/sgml/ref/create_user_mapping.sgml +++ b/doc/src/sgml/ref/create_user_mapping.sgml @@ -21,7 +21,7 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> -CREATE USER MAPPING FOR { <replaceable class="parameter">user_name</replaceable> | USER | CURRENT_USER | PUBLIC } +CREATE USER MAPPING [IF NOT EXISTS] FOR { <replaceable class="parameter">user_name</replaceable> | USER | CURRENT_USER | PUBLIC } SERVER <replaceable class="parameter">server_name</replaceable> [ OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [ , ... ] ) ] </synopsis> @@ -55,6 +55,18 @@ CREATE USER MAPPING FOR { <replaceable class="parameter">user_name</replaceable> <title>Parameters</title> <variablelist> + <varlistentry> + <term><literal>IF NOT EXISTS</></term> + <listitem> + <para> + Do not throw an error if a mapping of the given user to the given foreign + server already exists. A notice is issued in this case. Note that there + is no guarantee that the existing user mapping is anything like the one + that would have been created. + </para> + </listitem> + </varlistentry> + <varlistentry> <term><replaceable class="parameter">user_name</replaceable></term> <listitem> diff --git a/doc/src/sgml/ref/create_view.sgml b/doc/src/sgml/ref/create_view.sgml index 7ebbeeacb1..22f21c207f 100644 --- a/doc/src/sgml/ref/create_view.sgml +++ b/doc/src/sgml/ref/create_view.sgml @@ -91,13 +91,13 @@ CREATE [ OR REPLACE ] [ TEMP | TEMPORARY ] [ RECURSIVE ] VIEW <replaceable class <para> Creates a recursive view. The syntax <synopsis> -CREATE RECURSIVE VIEW <replaceable>name</> (<replaceable>columns</>) AS SELECT <replaceable>...</>; +CREATE RECURSIVE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> (<replaceable>column_names</>) AS SELECT <replaceable>...</>; </synopsis> is equivalent to <synopsis> -CREATE VIEW <replaceable>name</> AS WITH RECURSIVE <replaceable>name</> (<replaceable>columns</>) AS (SELECT <replaceable>...</>) SELECT <replaceable>columns</> FROM <replaceable>name</>; +CREATE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> AS WITH RECURSIVE <replaceable>view_name</> (<replaceable>column_names</>) AS (SELECT <replaceable>...</>) SELECT <replaceable>column_names</> FROM <replaceable>view_name</>; </synopsis> - A view column list must be specified for a recursive view. + A view column name list must be specified for a recursive view. </para> </listitem> </varlistentry> @@ -255,9 +255,10 @@ CREATE VIEW <replaceable>name</> AS WITH RECURSIVE <replaceable>name</> (<replac <programlisting> CREATE VIEW vista AS SELECT 'Hello World'; </programlisting> - is bad form in two ways: the column name defaults to <literal>?column?</>, - and the column data type defaults to <type>unknown</>. If you want a - string literal in a view's result, use something like: + is bad form because the column name defaults to <literal>?column?</>; + also, the column data type defaults to <type>text</>, which might not + be what you wanted. Better style for a string literal in a view's + result is something like: <programlisting> CREATE VIEW vista AS SELECT text 'Hello World' AS hello; </programlisting> @@ -466,11 +467,16 @@ CREATE VIEW comedies AS <para> Create a recursive view consisting of the numbers from 1 to 100: <programlisting> -CREATE RECURSIVE VIEW nums_1_100 (n) AS +CREATE RECURSIVE VIEW public.nums_1_100 (n) AS VALUES (1) UNION ALL SELECT n+1 FROM nums_1_100 WHERE n < 100; -</programlisting></para> +</programlisting> + Notice that although the recursive view's name is schema-qualified in this + <command>CREATE</>, its internal self-reference is not schema-qualified. + This is because the implicitly-created CTE's name cannot be + schema-qualified. + </para> </refsect1> <refsect1> diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml index c363bd4a56..9fc4c16a81 100644 --- a/doc/src/sgml/ref/createdb.sgml +++ b/doc/src/sgml/ref/createdb.sgml @@ -363,11 +363,11 @@ PostgreSQL documentation <para> To create the database <literal>demo</literal> using the server on host <literal>eden</>, port 5000, using the - <literal>LATIN1</literal> encoding scheme with a look at the - underlying command: + <literal>template0</literal> template database, here is the + command-line command and the underlying SQL command: <screen> -<prompt>$ </prompt><userinput>createdb -p 5000 -h eden -E LATIN1 -e demo</userinput> -<computeroutput>CREATE DATABASE demo ENCODING 'LATIN1';</computeroutput> +<prompt>$ </prompt><userinput>createdb -p 5000 -h eden -T template0 -e demo</userinput> +<computeroutput>CREATE DATABASE demo TEMPLATE template0;</computeroutput> </screen></para> </refsect1> diff --git a/doc/src/sgml/ref/createlang.sgml b/doc/src/sgml/ref/createlang.sgml deleted file mode 100644 index e9c95d3278..0000000000 --- a/doc/src/sgml/ref/createlang.sgml +++ /dev/null @@ -1,291 +0,0 @@ -<!-- -doc/src/sgml/ref/createlang.sgml -PostgreSQL documentation ---> - -<refentry id="APP-CREATELANG"> - <indexterm zone="app-createlang"> - <primary>createlang</primary> - </indexterm> - - <refmeta> - <refentrytitle><application>createlang</application></refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo>Application</refmiscinfo> - </refmeta> - - <refnamediv> - <refname>createlang</refname> - <refpurpose>install a <productname>PostgreSQL</productname> procedural language</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>createlang</command> - <arg rep="repeat"><replaceable>connection-option</replaceable></arg> - <arg choice="plain"><replaceable>langname</replaceable></arg> - <arg choice="opt"><replaceable>dbname</replaceable></arg> - </cmdsynopsis> - - <cmdsynopsis> - <command>createlang</command> - <arg rep="repeat"><replaceable>connection-option</replaceable></arg> - <group choice="plain"><arg choice="plain"><option>--list</option></arg><arg choice="plain"><option>-l</option></arg></group> - <arg choice="opt"><replaceable>dbname</replaceable></arg> - </cmdsynopsis> - </refsynopsisdiv> - - - <refsect1> - <title>Description</title> - - <para> - <application>createlang</application> is a utility for adding a - procedural language to a <productname>PostgreSQL</productname> database. - </para> - - <para> - <application>createlang</application> is just a wrapper around the - <xref linkend="sql-createextension"> SQL command. - </para> - - <caution> - <para> - <application>createlang</application> is deprecated and may be removed - in a future <productname>PostgreSQL</productname> release. Direct use - of the <command>CREATE EXTENSION</> command is recommended instead. - </para> - </caution> - </refsect1> - - - <refsect1> - <title>Options</title> - - <para> - <application>createlang</application> accepts the following command-line arguments: - - <variablelist> - <varlistentry> - <term><replaceable class="parameter">langname</replaceable></term> - <listitem> - <para> - Specifies the name of the procedural language to be - installed. (This name is lower-cased.) - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option><optional>-d</> <replaceable class="parameter">dbname</replaceable></></term> - <term><option><optional>--dbname=</><replaceable class="parameter">dbname</replaceable></></term> - <listitem> - <para> - Specifies the database to which the language should be added. - The default is to use the database with the same name as the - current system user. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-e</></term> - <term><option>--echo</></term> - <listitem> - <para> - Display SQL commands as they are executed. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-l</></term> - <term><option>--list</></term> - <listitem> - <para> - Show a list of already installed languages in the target database. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> - <listitem> - <para> - Print the <application>createlang</application> version and exit. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> - <listitem> - <para> - Show help about <application>createlang</application> command line - arguments, and exit. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - - <para> - <application>createlang</application> also accepts - the following command-line arguments for connection parameters: - - <variablelist> - <varlistentry> - <term><option>-h <replaceable class="parameter">host</replaceable></></term> - <term><option>--host=<replaceable class="parameter">host</replaceable></></term> - <listitem> - <para> - Specifies the host name of the machine on which the - server - is running. If the value begins with a slash, it is used - as the directory for the Unix domain socket. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></></term> - <listitem> - <para> - Specifies the TCP port or local Unix domain socket file - extension on which the server - is listening for connections. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-U <replaceable class="parameter">username</replaceable></></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></></term> - <listitem> - <para> - User name to connect as. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> - <listitem> - <para> - Never issue a password prompt. If the server requires - password authentication and a password is not available by - other means such as a <filename>.pgpass</filename> file, the - connection attempt will fail. This option can be useful in - batch jobs and scripts where no user is present to enter a - password. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-W</></term> - <term><option>--password</></term> - <listitem> - <para> - Force <application>createlang</application> to prompt for a - password before connecting to a database. - </para> - - <para> - This option is never essential, since - <application>createlang</application> will automatically prompt - for a password if the server demands password authentication. - However, <application>createlang</application> will waste a - connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra - connection attempt. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - </refsect1> - - - <refsect1> - <title>Environment</title> - - <variablelist> - <varlistentry> - <term><envar>PGDATABASE</envar></term> - <term><envar>PGHOST</envar></term> - <term><envar>PGPORT</envar></term> - <term><envar>PGUSER</envar></term> - - <listitem> - <para> - Default connection parameters - </para> - </listitem> - </varlistentry> - </variablelist> - - <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> - (see <xref linkend="libpq-envars">). - </para> - - </refsect1> - - - <refsect1> - <title>Diagnostics</title> - - <para> - Most error messages are self-explanatory. If not, run - <application>createlang</application> with the <option>--echo</option> - option and see the respective <acronym>SQL</acronym> command - for details. Also, any default connection settings and environment - variables used by the <application>libpq</application> front-end - library will apply. - </para> - </refsect1> - - - <refsect1> - <title>Notes</title> - - <para> - Use <xref linkend="app-droplang"> to remove a language. - </para> - </refsect1> - - - <refsect1> - <title>Examples</title> - - <para> - To install the language <literal>pltcl</literal> into the database - <literal>template1</literal>: -<screen> -<prompt>$ </prompt><userinput>createlang pltcl template1</userinput> -</screen> - Note that installing the language into <literal>template1</literal> - will cause it to be automatically installed into subsequently-created - databases as well. - </para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <simplelist type="inline"> - <member><xref linkend="app-droplang"></member> - <member><xref linkend="sql-createextension"></member> - <member><xref linkend="sql-createlanguage"></member> - </simplelist> - </refsect1> - -</refentry> diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml index 4332008c68..fda77976ff 100644 --- a/doc/src/sgml/ref/createuser.sgml +++ b/doc/src/sgml/ref/createuser.sgml @@ -124,8 +124,8 @@ PostgreSQL documentation <term><option>--encrypted</></term> <listitem> <para> - Encrypts the user's password stored in the database. If not - specified, the default password behavior is used. + This option is obsolete but still accepted for backward + compatibility. </para> </listitem> </varlistentry> @@ -205,17 +205,6 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-N</></term> - <term><option>--unencrypted</></term> - <listitem> - <para> - Does not encrypt the user's password stored in the database. If - not specified, the default password behavior is used. - </para> - </listitem> - </varlistentry> - - <varlistentry> <term><option>-P</></term> <term><option>--pwprompt</></term> <listitem> @@ -481,11 +470,7 @@ PostgreSQL documentation </screen> In the above example, the new password isn't actually echoed when typed, but we show what was typed for clarity. As you see, the password is - encrypted before it is sent to the client. If the option <option>--unencrypted</option> - is used, the password <emphasis>will</> appear in the echoed command - (and possibly also in the server log and elsewhere), - so you don't want to use <option>-e</> in that case, if - anyone else can see your screen. + encrypted before it is sent to the client. </para> </refsect1> diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml index ff0431d6e1..3009b172d5 100644 --- a/doc/src/sgml/ref/delete.sgml +++ b/doc/src/sgml/ref/delete.sgml @@ -41,8 +41,7 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ * <tip> <para> - <xref linkend="sql-truncate"> is a - <productname>PostgreSQL</productname> extension that provides a + <xref linkend="sql-truncate"> provides a faster mechanism to remove all rows from a table. </para> </tip> @@ -289,4 +288,12 @@ DELETE FROM tasks WHERE CURRENT OF c_tasks; to use <literal>WITH</> with <command>DELETE</>. </para> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-truncate"></member> + </simplelist> + </refsect1> </refentry> diff --git a/doc/src/sgml/ref/drop_aggregate.sgml b/doc/src/sgml/ref/drop_aggregate.sgml index c27c5eadf9..631b578df7 100644 --- a/doc/src/sgml/ref/drop_aggregate.sgml +++ b/doc/src/sgml/ref/drop_aggregate.sgml @@ -21,7 +21,7 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> -DROP AGGREGATE [ IF EXISTS ] <replaceable>name</replaceable> ( <replaceable>aggregate_signature</replaceable> ) [ CASCADE | RESTRICT ] +DROP AGGREGATE [ IF EXISTS ] <replaceable>name</replaceable> ( <replaceable>aggregate_signature</replaceable> ) [, ...] [ CASCADE | RESTRICT ] <phrase>where <replaceable>aggregate_signature</replaceable> is:</phrase> @@ -155,7 +155,14 @@ DROP AGGREGATE myavg(integer); DROP AGGREGATE myrank(VARIADIC "any" ORDER BY VARIADIC "any"); </programlisting> </para> - </refsect1> + + <para> + To remove multiple aggregate functions in one command: +<programlisting> +DROP AGGREGATE myavg(integer), myavg(bigint); +</programlisting> + </para> +</refsect1> <refsect1> <title>Compatibility</title> diff --git a/doc/src/sgml/ref/drop_foreign_data_wrapper.sgml b/doc/src/sgml/ref/drop_foreign_data_wrapper.sgml index 2e17a3d35f..933a51ff2d 100644 --- a/doc/src/sgml/ref/drop_foreign_data_wrapper.sgml +++ b/doc/src/sgml/ref/drop_foreign_data_wrapper.sgml @@ -21,7 +21,7 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> -DROP FOREIGN DATA WRAPPER [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [ CASCADE | RESTRICT ] +DROP FOREIGN DATA WRAPPER [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [, ...] [ CASCADE | RESTRICT ] </synopsis> </refsynopsisdiv> diff --git a/doc/src/sgml/ref/drop_foreign_table.sgml b/doc/src/sgml/ref/drop_foreign_table.sgml index f9d1e459d2..5a2b235d4e 100644 --- a/doc/src/sgml/ref/drop_foreign_table.sgml +++ b/doc/src/sgml/ref/drop_foreign_table.sgml @@ -1,4 +1,4 @@ -<!-- doc/src/sggml/ref/drop_foreign_table.sgml --> +<!-- doc/src/sgml/ref/drop_foreign_table.sgml --> <refentry id="SQL-DROPFOREIGNTABLE"> <indexterm zone="sql-dropforeigntable"> diff --git a/doc/src/sgml/ref/drop_function.sgml b/doc/src/sgml/ref/drop_function.sgml index 5883d13811..0aa984528d 100644 --- a/doc/src/sgml/ref/drop_function.sgml +++ b/doc/src/sgml/ref/drop_function.sgml @@ -21,7 +21,7 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> -DROP FUNCTION [ IF EXISTS ] <replaceable class="parameter">name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) +DROP FUNCTION [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] [, ...] [ CASCADE | RESTRICT ] </synopsis> </refsynopsisdiv> @@ -56,7 +56,8 @@ DROP FUNCTION [ IF EXISTS ] <replaceable class="parameter">name</replaceable> ( <term><replaceable class="parameter">name</replaceable></term> <listitem> <para> - The name (optionally schema-qualified) of an existing function. + The name (optionally schema-qualified) of an existing function. If no + argument list is specified, the name must be unique in its schema. </para> </listitem> </varlistentry> @@ -135,14 +136,46 @@ DROP FUNCTION [ IF EXISTS ] <replaceable class="parameter">name</replaceable> ( <programlisting> DROP FUNCTION sqrt(integer); </programlisting></para> + + <para> + Drop multiple functions in one command: +<programlisting> +DROP FUNCTION sqrt(integer), sqrt(bigint); +</programlisting></para> + + <para> + If the function name is unique in its schema, it can be referred to without + an argument list: +<programlisting> +DROP FUNCTION update_employee_salaries; +</programlisting> + Note that this is different from +<programlisting> +DROP FUNCTION update_employee_salaries(); +</programlisting> + which refers to a function with zero arguments, whereas the first variant + can refer to a function with any number of arguments, including zero, as + long as the name is unique. + </para> </refsect1> <refsect1 id="SQL-DROPFUNCTION-compatibility"> <title>Compatibility</title> <para> - A <command>DROP FUNCTION</command> statement is defined in the SQL - standard, but it is not compatible with this command. + This command conforms to the SQL standard, with + these <productname>PostgreSQL</productname> extensions: + <itemizedlist> + <listitem> + <para>The standard only allows one function to be dropped per command.</para> + </listitem> + <listitem> + <para>The <literal>IF EXISTS</literal> option</para> + </listitem> + <listitem> + <para>The ability to specify argument modes and names</para> + </listitem> + </itemizedlist> </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_language.sgml b/doc/src/sgml/ref/drop_language.sgml index 0facc62876..f014a74d45 100644 --- a/doc/src/sgml/ref/drop_language.sgml +++ b/doc/src/sgml/ref/drop_language.sgml @@ -120,7 +120,6 @@ DROP LANGUAGE plsample; <simplelist type="inline"> <member><xref linkend="sql-alterlanguage"></member> <member><xref linkend="sql-createlanguage"></member> - <member><xref linkend="app-droplang"></member> </simplelist> </refsect1> diff --git a/doc/src/sgml/ref/drop_operator.sgml b/doc/src/sgml/ref/drop_operator.sgml index 13dd974f38..fc82c3e0e3 100644 --- a/doc/src/sgml/ref/drop_operator.sgml +++ b/doc/src/sgml/ref/drop_operator.sgml @@ -21,7 +21,7 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> -DROP OPERATOR [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> ( { <replaceable class="PARAMETER">left_type</replaceable> | NONE } , { <replaceable class="PARAMETER">right_type</replaceable> | NONE } ) [ CASCADE | RESTRICT ] +DROP OPERATOR [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> ( { <replaceable class="PARAMETER">left_type</replaceable> | NONE } , { <replaceable class="PARAMETER">right_type</replaceable> | NONE } ) [, ...] [ CASCADE | RESTRICT ] </synopsis> </refsynopsisdiv> @@ -126,6 +126,12 @@ DROP OPERATOR ~ (none, bit); <programlisting> DROP OPERATOR ! (bigint, none); </programlisting></para> + + <para> + Remove multiple operators in one command: +<programlisting> +DROP OPERATOR ~ (none, bit), ! (bigint, none); +</programlisting></para> </refsect1> <refsect1> diff --git a/doc/src/sgml/ref/drop_publication.sgml b/doc/src/sgml/ref/drop_publication.sgml new file mode 100644 index 0000000000..1a1be579ad --- /dev/null +++ b/doc/src/sgml/ref/drop_publication.sgml @@ -0,0 +1,107 @@ +<!-- +doc/src/sgml/ref/drop_publication.sgml +PostgreSQL documentation +--> + +<refentry id="SQL-DROPPUBLICATION"> + <indexterm zone="sql-droppublication"> + <primary>DROP PUBLICATION</primary> + </indexterm> + + <refmeta> + <refentrytitle>DROP PUBLICATION</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>DROP PUBLICATION</refname> + <refpurpose>remove a publication</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +DROP PUBLICATION [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [, ...] [ CASCADE | RESTRICT ] +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>DROP PUBLICATION</command> removes an existing publication from + the database. + </para> + + <para> + A publication can only be dropped by its owner or a superuser. + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><literal>IF EXISTS</literal></term> + <listitem> + <para> + Do not throw an error if the extension does not exist. A notice is issued + in this case. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">name</replaceable></term> + <listitem> + <para> + The name of an existing publication. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <term><literal>RESTRICT</literal></term> + + <listitem> + <para> + These key words do not have any effect, since there are no dependencies + on publications. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para> + Drop a publication: +<programlisting> +DROP PUBLICATION mypublication; +</programlisting> + </para> + + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + <command>DROP PUBLICATION</command> is a <productname>PostgreSQL</> + extension. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-createpublication"></member> + <member><xref linkend="sql-alterpublication"></member> + </simplelist> + </refsect1> +</refentry> diff --git a/doc/src/sgml/ref/drop_server.sgml b/doc/src/sgml/ref/drop_server.sgml index 72c8656b49..247462d62a 100644 --- a/doc/src/sgml/ref/drop_server.sgml +++ b/doc/src/sgml/ref/drop_server.sgml @@ -21,7 +21,7 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> -DROP SERVER [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [ CASCADE | RESTRICT ] +DROP SERVER [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [, ...] [ CASCADE | RESTRICT ] </synopsis> </refsynopsisdiv> diff --git a/doc/src/sgml/ref/drop_statistics.sgml b/doc/src/sgml/ref/drop_statistics.sgml new file mode 100644 index 0000000000..ef659fca61 --- /dev/null +++ b/doc/src/sgml/ref/drop_statistics.sgml @@ -0,0 +1,98 @@ +<!-- +doc/src/sgml/ref/drop_statistics.sgml +PostgreSQL documentation +--> + +<refentry id="SQL-DROPSTATISTICS"> + <indexterm zone="sql-dropstatistics"> + <primary>DROP STATISTICS</primary> + </indexterm> + + <refmeta> + <refentrytitle>DROP STATISTICS</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>DROP STATISTICS</refname> + <refpurpose>remove extended statistics</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +DROP STATISTICS [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [, ...] +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>DROP STATISTICS</command> removes statistics object(s) from the + database. Only the statistics object's owner, the schema owner, or a + superuser can drop a statistics object. + </para> + + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><literal>IF EXISTS</literal></term> + <listitem> + <para> + Do not throw an error if the statistics object does not exist. A notice + is issued in this case. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">name</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of the statistics object to drop. + </para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para> + To destroy two statistics objects in different schemas, without failing + if they don't exist: + +<programlisting> +DROP STATISTICS IF EXISTS + accounting.users_uid_creation, + public.grants_user_role; +</programlisting> + </para> + + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + There is no <command>DROP STATISTICS</command> command in the SQL standard. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-alterstatistics"></member> + <member><xref linkend="sql-createstatistics"></member> + </simplelist> + </refsect1> + +</refentry> diff --git a/doc/src/sgml/ref/drop_subscription.sgml b/doc/src/sgml/ref/drop_subscription.sgml new file mode 100644 index 0000000000..4f34a35eef --- /dev/null +++ b/doc/src/sgml/ref/drop_subscription.sgml @@ -0,0 +1,105 @@ +<!-- +doc/src/sgml/ref/drop_subscription.sgml +PostgreSQL documentation +--> + +<refentry id="SQL-DROPSUBSCRIPTION"> + <indexterm zone="sql-dropsubscription"> + <primary>DROP SUBSCRIPTION</primary> + </indexterm> + + <refmeta> + <refentrytitle>DROP SUBSCRIPTION</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>DROP SUBSCRIPTION</refname> + <refpurpose>remove a subscription</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +DROP SUBSCRIPTION [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [ CASCADE | RESTRICT ] +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>DROP SUBSCRIPTION</command> removes a subscription from the + database cluster. + </para> + + <para> + A subscription can only be dropped by a superuser. + </para> + + <para> + <command>DROP SUBSCRIPTION</command> cannot be executed inside a + transaction block if the subscription is associated with a replication + slot. (You can use <command>ALTER SUBSCRIPTION</command> to unset the + slot.) + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">name</replaceable></term> + <listitem> + <para> + The name of a subscription to be dropped. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <term><literal>RESTRICT</literal></term> + + <listitem> + <para> + These key words do not have any effect, since there are no dependencies + on subscriptions. + </para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para> + Drop a subscription: +<programlisting> +DROP SUBSCRIPTION mysub; +</programlisting> + </para> + + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + <command>DROP SUBSCRIPTION</command> is a <productname>PostgreSQL</> + extension. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-createsubscription"></member> + <member><xref linkend="sql-altersubscription"></member> + </simplelist> + </refsect1> +</refentry> diff --git a/doc/src/sgml/ref/droplang.sgml b/doc/src/sgml/ref/droplang.sgml deleted file mode 100644 index 86f05d6b05..0000000000 --- a/doc/src/sgml/ref/droplang.sgml +++ /dev/null @@ -1,288 +0,0 @@ -<!-- -doc/src/sgml/ref/droplang.sgml -PostgreSQL documentation ---> - -<refentry id="APP-DROPLANG"> - <indexterm zone="app-droplang"> - <primary>droplang</primary> - </indexterm> - - <refmeta> - <refentrytitle><application>droplang</application></refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo>Application</refmiscinfo> - </refmeta> - - <refnamediv> - <refname>droplang</refname> - <refpurpose>remove a <productname>PostgreSQL</productname> procedural language</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>droplang</command> - <arg rep="repeat"><replaceable>connection-option</replaceable></arg> - <arg choice="plain"><replaceable>langname</replaceable></arg> - <arg choice="opt"><replaceable>dbname</replaceable></arg> - </cmdsynopsis> - - <cmdsynopsis> - <command>droplang</command> - <arg rep="repeat"><replaceable>connection-option</replaceable></arg> - <group choice="plain"><arg choice="plain"><option>--list</option></arg><arg choice="plain"><option>-l</option></arg></group> - <arg choice="opt"><replaceable>dbname</replaceable></arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1 id="R1-APP-DROPLANG-1"> - <title> - Description - </title> - - <para> - <application>droplang</application> is a utility for removing an - existing procedural language from a - <productname>PostgreSQL</productname> database. - </para> - - <para> - <application>droplang</application> is just a wrapper around the - <xref linkend="sql-dropextension"> SQL command. - </para> - - <caution> - <para> - <application>droplang</application> is deprecated and may be removed - in a future <productname>PostgreSQL</productname> release. Direct use - of the <command>DROP EXTENSION</> command is recommended instead. - </para> - </caution> - </refsect1> - - - <refsect1> - <title>Options</title> - - <para> - <application>droplang</application> accepts the following command line arguments: - - <variablelist> - <varlistentry> - <term><replaceable class="parameter">langname</replaceable></term> - <listitem> - <para> - Specifies the name of the procedural language to be removed. - (This name is lower-cased.) - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option><optional>-d</> <replaceable class="parameter">dbname</replaceable></></term> - <term><option><optional>--dbname=</><replaceable class="parameter">dbname</replaceable></></term> - <listitem> - <para> - Specifies from which database the language should be removed. - The default is to use the database with the same name as the - current system user. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-e</></term> - <term><option>--echo</></term> - <listitem> - <para> - Display SQL commands as they are executed. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-l</></term> - <term><option>--list</></term> - <listitem> - <para> - Show a list of already installed languages in the target database. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> - <listitem> - <para> - Print the <application>droplang</application> version and exit. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> - <listitem> - <para> - Show help about <application>droplang</application> command line - arguments, and exit. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - - <para> - <application>droplang</application> also accepts - the following command line arguments for connection parameters: - - <variablelist> - <varlistentry> - <term><option>-h <replaceable class="parameter">host</replaceable></></term> - <term><option>--host=<replaceable class="parameter">host</replaceable></></term> - <listitem> - <para> - Specifies the host name of the machine on which the - server - is running. If host begins with a slash, it is used - as the directory for the Unix domain socket. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></></term> - <listitem> - <para> - Specifies the Internet TCP/IP port or local Unix domain socket file - extension on which the server - is listening for connections. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-U <replaceable class="parameter">username</replaceable></></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></></term> - <listitem> - <para> - User name to connect as. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> - <listitem> - <para> - Never issue a password prompt. If the server requires - password authentication and a password is not available by - other means such as a <filename>.pgpass</filename> file, the - connection attempt will fail. This option can be useful in - batch jobs and scripts where no user is present to enter a - password. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-W</></term> - <term><option>--password</></term> - <listitem> - <para> - Force <application>droplang</application> to prompt for a - password before connecting to a database. - </para> - - <para> - This option is never essential, since - <application>droplang</application> will automatically prompt - for a password if the server demands password authentication. - However, <application>droplang</application> will waste a - connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra - connection attempt. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - </refsect1> - - - <refsect1> - <title>Environment</title> - - <variablelist> - <varlistentry> - <term><envar>PGDATABASE</envar></term> - <term><envar>PGHOST</envar></term> - <term><envar>PGPORT</envar></term> - <term><envar>PGUSER</envar></term> - - <listitem> - <para> - Default connection parameters - </para> - </listitem> - </varlistentry> - </variablelist> - - <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> - (see <xref linkend="libpq-envars">). - </para> - - </refsect1> - - - <refsect1> - <title>Diagnostics</title> - - <para> - Most error messages are self-explanatory. If not, run - <application>droplang</application> with the <option>--echo</option> - option and see under the respective <acronym>SQL</acronym> command - for details. Also, any default connection settings and environment - variables used by the <application>libpq</application> front-end - library will apply. - </para> - </refsect1> - - - <refsect1> - <title>Notes</title> - - <para> - Use <xref linkend="app-createlang"> to add a language. - </para> - </refsect1> - - - <refsect1> - <title>Examples</title> - - <para> - To remove the language <literal>pltcl</literal>: -<screen> -<prompt>$ </prompt><userinput>droplang pltcl dbname</userinput> -</screen></para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <simplelist type="inline"> - <member><xref linkend="app-createlang"></member> - <member><xref linkend="sql-dropextension"></member> - <member><xref linkend="sql-droplanguage"></member> - </simplelist> - </refsect1> - -</refentry> diff --git a/doc/src/sgml/ref/ecpg-ref.sgml b/doc/src/sgml/ref/ecpg-ref.sgml index 029bd4a4d2..8bfb47c4d7 100644 --- a/doc/src/sgml/ref/ecpg-ref.sgml +++ b/doc/src/sgml/ref/ecpg-ref.sgml @@ -42,11 +42,9 @@ PostgreSQL documentation <para> <command>ecpg</command> will convert each input file given on the command line to the corresponding C output file. Input files - preferably have the extension <filename>.pgc</filename>, in which - case the extension will be replaced by <filename>.c</filename> to - determine the output file name. If the extension of the input file - is not <filename>.pgc</filename>, then the output file name is - computed by appending <literal>.c</literal> to the full file name. + preferably have the extension <filename>.pgc</filename>. + The extension will be replaced by <filename>.c</filename> to + determine the output file name. The output file name can also be overridden using the <option>-o</option> option. </para> diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml index eb48b9614f..5bd3438197 100644 --- a/doc/src/sgml/ref/explain.sgml +++ b/doc/src/sgml/ref/explain.sgml @@ -41,6 +41,7 @@ EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="parameter">statement</replac COSTS [ <replaceable class="parameter">boolean</replaceable> ] BUFFERS [ <replaceable class="parameter">boolean</replaceable> ] TIMING [ <replaceable class="parameter">boolean</replaceable> ] + SUMMARY [ <replaceable class="parameter">boolean</replaceable> ] FORMAT { TEXT | XML | JSON | YAML } </synopsis> </refsynopsisdiv> @@ -225,6 +226,21 @@ ROLLBACK; </varlistentry> <varlistentry> + <term><literal>SUMMARY</literal></term> + <listitem> + <para> + Include summary information (eg: totalled timing information) after the + query plan. Summary information is included by default when + <literal>ANALYZE</literal> is used but otherwise is not included by + default, but can be enabled using this option. Planning time in + <command>EXPLAIN EXECUTE</command> includes the time required to fetch + the plan from the cache and the time required for re-planning, if + necessary. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><literal>FORMAT</literal></term> <listitem> <para> diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml index cd8f3f50ba..c63252ca24 100644 --- a/doc/src/sgml/ref/grant.sgml +++ b/doc/src/sgml/ref/grant.sgml @@ -55,7 +55,7 @@ GRANT { USAGE | ALL [ PRIVILEGES ] } TO <replaceable class="PARAMETER">role_specification</replaceable> [, ...] [ WITH GRANT OPTION ] GRANT { EXECUTE | ALL [ PRIVILEGES ] } - ON { FUNCTION <replaceable>function_name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">arg_name</replaceable> ] <replaceable class="parameter">arg_type</replaceable> [, ...] ] ) [, ...] + ON { FUNCTION <replaceable>function_name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">arg_name</replaceable> ] <replaceable class="parameter">arg_type</replaceable> [, ...] ] ) ] [, ...] | ALL FUNCTIONS IN SCHEMA <replaceable class="PARAMETER">schema_name</replaceable> [, ...] } TO <replaceable class="PARAMETER">role_specification</replaceable> [, ...] [ WITH GRANT OPTION ] @@ -177,7 +177,7 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace <variablelist> <varlistentry> - <term>SELECT</term> + <term><literal>SELECT</literal></term> <listitem> <para> Allows <xref linkend="sql-select"> from @@ -196,7 +196,7 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace </varlistentry> <varlistentry> - <term>INSERT</term> + <term><literal>INSERT</literal></term> <listitem> <para> Allows <xref linkend="sql-insert"> of a new @@ -209,7 +209,7 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace </varlistentry> <varlistentry> - <term>UPDATE</term> + <term><literal>UPDATE</literal></term> <listitem> <para> Allows <xref linkend="sql-update"> of any @@ -231,7 +231,7 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace </varlistentry> <varlistentry> - <term>DELETE</term> + <term><literal>DELETE</literal></term> <listitem> <para> Allows <xref linkend="sql-delete"> of a row @@ -244,7 +244,7 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace </varlistentry> <varlistentry> - <term>TRUNCATE</term> + <term><literal>TRUNCATE</literal></term> <listitem> <para> Allows <xref linkend="sql-truncate"> on @@ -254,19 +254,18 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace </varlistentry> <varlistentry> - <term>REFERENCES</term> + <term><literal>REFERENCES</literal></term> <listitem> <para> - To create a foreign key constraint, it is - necessary to have this privilege on both the referencing and - referenced columns. The privilege may be granted for all columns - of a table, or just specific columns. + Allows creation of a foreign key constraint referencing the specified + table, or specified column(s) of the table. (See the + <xref linkend="sql-createtable"> statement.) </para> </listitem> </varlistentry> <varlistentry> - <term>TRIGGER</term> + <term><literal>TRIGGER</literal></term> <listitem> <para> Allows the creation of a trigger on the specified table. (See the @@ -276,10 +275,10 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace </varlistentry> <varlistentry> - <term>CREATE</term> + <term><literal>CREATE</literal></term> <listitem> <para> - For databases, allows new schemas to be created within the database. + For databases, allows new schemas and publications to be created within the database. </para> <para> For schemas, allows new objects to be created within the schema. @@ -296,7 +295,7 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace </varlistentry> <varlistentry> - <term>CONNECT</term> + <term><literal>CONNECT</literal></term> <listitem> <para> Allows the user to connect to the specified database. This @@ -307,8 +306,8 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace </varlistentry> <varlistentry> - <term>TEMPORARY</term> - <term>TEMP</term> + <term><literal>TEMPORARY</literal></term> + <term><literal>TEMP</literal></term> <listitem> <para> Allows temporary tables to be created while using the specified database. @@ -317,7 +316,7 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace </varlistentry> <varlistentry> - <term>EXECUTE</term> + <term><literal>EXECUTE</literal></term> <listitem> <para> Allows the use of the specified function and the use of any @@ -329,7 +328,7 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace </varlistentry> <varlistentry> - <term>USAGE</term> + <term><literal>USAGE</literal></term> <listitem> <para> For procedural languages, allows the use of the specified language for @@ -351,7 +350,7 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace <function>currval</function> and <function>nextval</function> functions. </para> <para> - For types and domains, this privilege allow the use of the type or + For types and domains, this privilege allows the use of the type or domain in the creation of tables, functions, and other schema objects. (Note that it does not control general <quote>usage</quote> of the type, such as values of the type appearing in queries. It only prevents @@ -360,19 +359,19 @@ GRANT <replaceable class="PARAMETER">role_name</replaceable> [, ...] TO <replace which could prevent the owner from changing the type later.) </para> <para> - For foreign-data wrappers, this privilege enables the grantee - to create new servers using that foreign-data wrapper. + For foreign-data wrappers, this privilege allows creation of + new servers using the foreign-data wrapper. </para> <para> - For servers, this privilege enables the grantee to create foreign - tables using the server, and also to create, alter, or drop their own - user's user mappings associated with that server. + For servers, this privilege allows creation of foreign tables using + the server. Grantees may also create, alter, or drop their own + user mappings associated with that server. </para> </listitem> </varlistentry> <varlistentry> - <term>ALL PRIVILEGES</term> + <term><literal>ALL PRIVILEGES</literal></term> <listitem> <para> Grant all of the available privileges at once. diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml index 5c20edf493..4aed43068e 100644 --- a/doc/src/sgml/ref/initdb.sgml +++ b/doc/src/sgml/ref/initdb.sgml @@ -127,11 +127,17 @@ Datanode. A database <term><option>--auth=<replaceable class="parameter">authmethod</replaceable></option></term> <listitem> <para> - This option specifies the authentication method for local users used - in <filename>pg_hba.conf</> (<literal>host</literal> - and <literal>local</literal> lines). Do not use <literal>trust</> - unless you trust all local users on your system. <literal>trust</> is - the default for ease of installation. + This option specifies the default authentication method for local + users used in <filename>pg_hba.conf</> (<literal>host</literal> + and <literal>local</literal> lines). <command>initdb</command> will + prepopulate <filename>pg_hba.conf</filename> entries using the + specified authentication method for non-replication as well as + replication connections. + </para> + + <para> + Do not use <literal>trust</> unless you trust all local users on your + system. <literal>trust</> is the default for ease of installation. </para> </listitem> </varlistentry> @@ -254,7 +260,7 @@ Datanode. A database <varlistentry> <term><option>-N</option></term> - <term><option>--nosync</option></term> + <term><option>--no-sync</option></term> <listitem> <para> By default, <command>initdb</command> will wait for all files to be @@ -330,10 +336,10 @@ Datanode. A database <varlistentry> <term><option>-X <replaceable class="parameter">directory</replaceable></option></term> - <term><option>--xlogdir=<replaceable class="parameter">directory</replaceable></option></term> + <term><option>--waldir=<replaceable class="parameter">directory</replaceable></option></term> <listitem> <para> - This option specifies the directory where the transaction log + This option specifies the directory where the write-ahead log should be stored. </para> </listitem> @@ -374,7 +380,7 @@ Datanode. A database <varlistentry> <term><option>-n</option></term> - <term><option>--noclean</option></term> + <term><option>--no-clean</option></term> <listitem> <para> By default, when <command>initdb</command> diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml index 06f416039b..95aa77b907 100644 --- a/doc/src/sgml/ref/insert.sgml +++ b/doc/src/sgml/ref/insert.sgml @@ -23,6 +23,7 @@ PostgreSQL documentation <synopsis> [ WITH [ RECURSIVE ] <replaceable class="parameter">with_query</replaceable> [, ...] ] INSERT INTO <replaceable class="PARAMETER">table_name</replaceable> [ AS <replaceable class="parameter">alias</replaceable> ] [ ( <replaceable class="PARAMETER">column_name</replaceable> [, ...] ) ] + [ OVERRIDING { SYSTEM | USER} VALUE ] { DEFAULT VALUES | VALUES ( { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } [, ...] ) [, ...] | <replaceable class="PARAMETER">query</replaceable> } [ ON CONFLICT [ <replaceable class="parameter">conflict_target</replaceable> ] <replaceable class="parameter">conflict_action</replaceable> ] [ RETURNING * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] [, ...] ] @@ -36,7 +37,7 @@ INSERT INTO <replaceable class="PARAMETER">table_name</replaceable> [ AS <replac DO NOTHING DO UPDATE SET { <replaceable class="PARAMETER">column_name</replaceable> = { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } | - ( <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> ) } [, ...] [ WHERE <replaceable class="PARAMETER">condition</replaceable> ] @@ -174,9 +175,9 @@ INSERT INTO <replaceable class="PARAMETER">table_name</replaceable> [ AS <replac A substitute name for <replaceable class="PARAMETER">table_name</replaceable>. When an alias is provided, it completely hides the actual name of the table. - This is particularly useful when <literal>ON CONFLICT DO - UPDATE</literal> targets a table named excluded, since that's - also the name of the special table representing rows proposed + This is particularly useful when <literal>ON CONFLICT DO UPDATE</> + targets a table named <varname>excluded</>, since that will otherwise + be taken as the name of the special table representing rows proposed for insertion. </para> </listitem> @@ -202,10 +203,43 @@ INSERT INTO <replaceable class="PARAMETER">table_name</replaceable> [ AS <replac </varlistentry> <varlistentry> + <term><literal>OVERRIDING SYSTEM VALUE</literal></term> + <listitem> + <para> + Without this clause, it is an error to specify an explicit value + (other than <literal>DEFAULT</literal>) for an identity column defined + as <literal>GENERATED ALWAYS</literal>. This clause overrides that + restriction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>OVERRIDING USER VALUE</literal></term> + <listitem> + <para> + If this clause is specified, then any values supplied for identity + columns defined as <literal>GENERATED BY DEFAULT</literal> are ignored + and the default sequence-generated values are applied. + </para> + + <para> + This clause is useful for example when copying values between tables. + Writing <literal>INSERT INTO tbl2 OVERRIDING USER VALUE SELECT * FROM + tbl1</literal> will copy from <literal>tbl1</literal> all columns that + are not identity columns in <literal>tbl2</literal> but will continue + the sequence counters for any identity columns. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><literal>DEFAULT VALUES</literal></term> <listitem> <para> All columns will be filled with their default values. + (An <literal>OVERRIDING</literal> clause is not permitted in this + form.) </para> </listitem> </varlistentry> @@ -528,6 +562,17 @@ INSERT <replaceable>oid</replaceable> <replaceable class="parameter">count</repl </refsect1> <refsect1> + <title>Notes</title> + + <para> + If the specified table is a partitioned table, each row is routed to + the appropriate partition and inserted into it. If the specified table + is a partition, an error will occur if one of the input rows violates + the partition constraint. + </para> + </refsect1> + + <refsect1> <title>Examples</title> <para> @@ -700,6 +745,13 @@ INSERT INTO distributors (did, dname) VALUES (10, 'Conrad International') </para> <para> + The SQL standard specifies that <literal>OVERRIDING SYSTEM VALUE</literal> + can only be specified if an identity column that is generated always + exists. PostgreSQL allows the clause in any case and ignores it if it is + not applicable. + </para> + + <para> Possible limitations of the <replaceable class="PARAMETER">query</replaceable> clause are documented under <xref linkend="sql-select">. diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml index 03615da480..2454d35af3 100644 --- a/doc/src/sgml/ref/pg_basebackup.sgml +++ b/doc/src/sgml/ref/pg_basebackup.sgml @@ -56,7 +56,7 @@ PostgreSQL documentation and <filename>pg_hba.conf</filename> must explicitly permit the replication connection. The server must also be configured with <xref linkend="guc-max-wal-senders"> set high enough to leave at least - one session available for the backup. + one session available for the backup and one for WAL streaming (if used). </para> <para> @@ -85,10 +85,8 @@ PostgreSQL documentation </listitem> <listitem> <para> - There is no guarantee that all WAL files required for the backup are archived - at the end of backup. If you are planning to use the backup for an archive - recovery and want to ensure that all required files are available at that moment, - you need to include them into the backup by using <literal>-x</> option. + If you are using <literal>-X none</>, there is no guarantee that all + WAL files required for the backup are archived at the end of backup. </para> </listitem> <listitem> @@ -180,7 +178,8 @@ PostgreSQL documentation target directory, the tar contents will be written to standard output, suitable for piping to for example <productname>gzip</productname>. This is only possible if - the cluster has no additional tablespaces. + the cluster has no additional tablespaces and WAL + streaming is not used. </para> </listitem> </varlistentry> @@ -241,6 +240,31 @@ PostgreSQL documentation the server does not remove any necessary WAL data in the time between the end of the base backup and the start of streaming replication. </para> + <para> + If this option is not specified and the server supports temporary + replication slots (version 10 and later), then a temporary replication + slot is automatically used for WAL streaming. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-slot</option></term> + <listitem> + <para> + This option prevents the creation of a temporary replication slot + during the backup even if it's supported by the server. + </para> + <para> + Temporary replication slots are created by default if no slot name + is given with the option <option>-S</option> when using log streaming. + </para> + <para> + The main purpose of this option is to allow taking a base backup when + the server is out of free replication slots. Using replication slots + is almost always preferred, because it prevents needed WAL from being + removed by the server during the backup. + </para> </listitem> </varlistentry> @@ -272,57 +296,60 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--xlogdir=<replaceable class="parameter">xlogdir</replaceable></option></term> + <term><option>--waldir=<replaceable class="parameter">waldir</replaceable></option></term> <listitem> <para> - Specifies the location for the transaction log directory. - <replaceable>xlogdir</replaceable> must be an absolute path. - The transaction log directory can only be specified when + Specifies the location for the write-ahead log directory. + <replaceable>waldir</replaceable> must be an absolute path. + The write-ahead log directory can only be specified when the backup is in plain mode. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-x</option></term> - <term><option>--xlog</option></term> - <listitem> - <para> - Using this option is equivalent of using <literal>-X</literal> with - method <literal>fetch</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> <term><option>-X <replaceable class="parameter">method</replaceable></option></term> - <term><option>--xlog-method=<replaceable class="parameter">method</replaceable></option></term> + <term><option>--wal-method=<replaceable class="parameter">method</replaceable></option></term> <listitem> <para> - Includes the required transaction log files (WAL files) in the - backup. This will include all transaction logs generated during - the backup. If this option is specified, it is possible to start - a postmaster directly in the extracted directory without the need - to consult the log archive, thus making this a completely standalone - backup. + Includes the required write-ahead log files (WAL files) in the + backup. This will include all write-ahead logs generated during + the backup. Unless the method <literal>none</literal> is specified, + it is possible to start a postmaster directly in the extracted + directory without the need to consult the log archive, thus + making this a completely standalone backup. </para> <para> - The following methods for collecting the transaction logs are + The following methods for collecting the write-ahead logs are supported: <variablelist> <varlistentry> + <term><literal>n</literal></term> + <term><literal>none</literal></term> + <listitem> + <para> + Don't include write-ahead log in the backup. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><literal>f</literal></term> <term><literal>fetch</literal></term> <listitem> <para> - The transaction log files are collected at the end of the backup. + The write-ahead log files are collected at the end of the backup. Therefore, it is necessary for the <xref linkend="guc-wal-keep-segments"> parameter to be set high enough that the log is not removed before the end of the backup. If the log has been rotated when it's time to transfer it, the backup will fail and be unusable. </para> + <para> + The write-ahead log files will be written to + the <filename>base.tar</filename> file. + </para> </listitem> </varlistentry> @@ -331,13 +358,21 @@ PostgreSQL documentation <term><literal>stream</literal></term> <listitem> <para> - Stream the transaction log while the backup is created. This will + Stream the write-ahead log while the backup is created. This will open a second connection to the server and start streaming the - transaction log in parallel while running the backup. Therefore, + write-ahead log in parallel while running the backup. Therefore, it will use up two connections configured by the <xref linkend="guc-max-wal-senders"> parameter. As long as the - client can keep up with transaction log received, using this mode - requires no extra transaction logs to be saved on the master. + client can keep up with write-ahead log received, using this mode + requires no extra write-ahead logs to be saved on the master. + </para> + <para> + The write-ahead log files are written to a separate file + named <filename>pg_wal.tar</filename> (if the server is a version + earlier than 10, the file will be named <filename>pg_xlog.tar</filename>). + </para> + <para> + This value is the default. </para> </listitem> </varlistentry> @@ -353,7 +388,8 @@ PostgreSQL documentation <para> Enables gzip compression of tar file output, with the default compression level. Compression is only available when using - the tar format. + the tar format, and the suffix <filename>.gz</filename> will + automatically be added to all tar filenames. </para> </listitem> </varlistentry> @@ -366,7 +402,8 @@ PostgreSQL documentation Enables gzip compression of tar file output, and specifies the compression level (0 through 9, 0 being no compression and 9 being best compression). Compression is only available when using the tar - format. + format, and the suffix <filename>.gz</filename> will + automatically be added to all tar filenames. </para> </listitem> </varlistentry> @@ -382,7 +419,7 @@ PostgreSQL documentation <term><option>--checkpoint=<replaceable class="parameter">fast|spread</replaceable></option></term> <listitem> <para> - Sets checkpoint mode to fast or spread (default) (see <xref linkend="backup-lowlevel-base-backup">). + Sets checkpoint mode to fast (immediate) or spread (default) (see <xref linkend="backup-lowlevel-base-backup">). </para> </listitem> </varlistentry> @@ -399,6 +436,24 @@ PostgreSQL documentation </varlistentry> <varlistentry> + <term><option>-n</option></term> + <term><option>--no-clean</option></term> + <listitem> + <para> + By default, when <command>pg_basebackup</command> aborts with an + error, it removes any directories it might have created before + discovering that it cannot finish the job (for example, data directory + and write-ahead log directory). This option inhibits tidying-up and is + thus useful for debugging. + </para> + + <para> + Note that tablespace directories are not cleaned up either way. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>-P</option></term> <term><option>--progress</option></term> <listitem> @@ -421,6 +476,21 @@ PostgreSQL documentation </varlistentry> <varlistentry> + <term><option>-N</option></term> + <term><option>--no-sync</option></term> + <listitem> + <para> + By default, <command>pg_basebackup</command> will wait for all files + to be written safely to disk. This option causes + <command>pg_basebackup</command> to return without waiting, which is + faster, but means that a subsequent operating system crash can leave + the base backup corrupt. Generally, this option is useful for testing + but should not be used when creating a production installation. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>-v</option></term> <term><option>--verbose</option></term> <listitem> @@ -590,12 +660,22 @@ PostgreSQL documentation <title>Notes</title> <para> + At the beginning of the backup, a checkpoint needs to be written on the + server the backup is taken from. Especially if the option + <literal>--checkpoint=fast</literal> is not used, this can take some time + during which <application>pg_basebackup</application> will be appear + to be idle. + </para> + + <para> The backup will include all files in the data directory and tablespaces, including the configuration files and any additional files placed in the - directory by third parties. But only regular files and directories are - copied. Symbolic links (other than those used for tablespaces) and special - device files are skipped. (See <xref linkend="protocol-replication"> for - the precise details.) + directory by third parties, except certain temporary files managed by + PostgreSQL. But only regular files and directories are copied, except that + symbolic links used for tablespaces are preserved. Symbolic links pointing + to certain directories known to PostgreSQL are copied as empty directories. + Other symbolic links and special device files are skipped. + See <xref linkend="protocol-replication"> for the precise details. </para> <para> @@ -652,7 +732,7 @@ PostgreSQL documentation To create a backup of a single-tablespace local database and compress this with <productname>bzip2</productname>: <screen> -<prompt>$</prompt> <userinput>pg_basebackup -D - -Ft | bzip2 > backup.tar.bz2</userinput> +<prompt>$</prompt> <userinput>pg_basebackup -D - -Ft -X fetch | bzip2 > backup.tar.bz2</userinput> </screen> (This command will fail if there are multiple tablespaces in the database.) diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml index fd73840d51..a6f27ec54d 100644 --- a/doc/src/sgml/ref/pg_ctl-ref.sgml +++ b/doc/src/sgml/ref/pg_ctl-ref.sgml @@ -23,19 +23,19 @@ PostgreSQL documentation <cmdsynopsis> <command>pg_ctl</command> <arg choice="plain"><option>init[db]</option></arg> - <arg choice="opt"><option>-s</option></arg> <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg> + <arg choice="opt"><option>-s</option></arg> <arg choice="opt"><option>-o</option> <replaceable>initdb-options</replaceable></arg> </cmdsynopsis> <cmdsynopsis> <command>pg_ctl</command> <arg choice="plain"><option>start</option></arg> - <arg choice="opt"><option>-w</option></arg> - <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg> - <arg choice="opt"><option>-s</option></arg> <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg> <arg choice="opt"><option>-l</option> <replaceable>filename</replaceable></arg> + <arg choice="opt"><option>-W</option></arg> + <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg> + <arg choice="opt"><option>-s</option></arg> <arg choice="opt"><option>-o</option> <replaceable>options</replaceable></arg> <arg choice="opt"><option>-p</option> <replaceable>path</replaceable></arg> <arg choice="opt"><option>-c</option></arg> @@ -45,9 +45,6 @@ PostgreSQL documentation <cmdsynopsis> <command>pg_ctl</command> <arg choice="plain"><option>stop</option></arg> - <arg choice="opt"><option>-W</option></arg> - <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg> - <arg choice="opt"><option>-s</option></arg> <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg> <arg choice="opt"><option>-m</option> <group choice="plain"> @@ -56,16 +53,15 @@ PostgreSQL documentation <arg choice="plain"><option>i[mmediate]</option></arg> </group> </arg> + <arg choice="opt"><option>-W</option></arg> + <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg> + <arg choice="opt"><option>-s</option></arg> </cmdsynopsis> <cmdsynopsis> <command>pg_ctl</command> <arg choice="plain"><option>restart</option></arg> - <arg choice="opt"><option>-w</option></arg> - <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg> - <arg choice="opt"><option>-s</option></arg> <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg> - <arg choice="opt"><option>-c</option></arg> <arg choice="opt"><option>-m</option> <group choice="plain"> <arg choice="plain"><option>s[mart]</option></arg> @@ -73,15 +69,19 @@ PostgreSQL documentation <arg choice="plain"><option>i[mmediate]</option></arg> </group> </arg> + <arg choice="opt"><option>-W</option></arg> + <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg> + <arg choice="opt"><option>-s</option></arg> <arg choice="opt"><option>-o</option> <replaceable>options</replaceable></arg> <arg>-Z <replaceable>nodeopt</replaceable></arg> + <arg choice="opt"><option>-c</option></arg> </cmdsynopsis> <cmdsynopsis> <command>pg_ctl</command> <arg choice="plain"><option>reload</option></arg> - <arg choice="opt"><option>-s</option></arg> <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg> + <arg choice="opt"><option>-s</option></arg> </cmdsynopsis> <cmdsynopsis> @@ -93,8 +93,10 @@ PostgreSQL documentation <cmdsynopsis> <command>pg_ctl</command> <arg choice="plain"><option>promote</option></arg> - <arg choice="opt"><option>-s</option></arg> <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg> + <arg choice="opt"><option>-W</option></arg> + <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg> + <arg choice="opt"><option>-s</option></arg> </cmdsynopsis> <cmdsynopsis> @@ -104,20 +106,23 @@ PostgreSQL documentation <arg choice="plain"><replaceable>process_id</replaceable></arg> </cmdsynopsis> + <para>On Microsoft Windows, also:</para> + <cmdsynopsis> <command>pg_ctl</command> <arg choice="plain"><option>register</option></arg> + <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg> <arg choice="opt"><option>-N</option> <replaceable>servicename</replaceable></arg> <arg choice="opt"><option>-U</option> <replaceable>username</replaceable></arg> <arg choice="opt"><option>-P</option> <replaceable>password</replaceable></arg> - <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg> <arg choice="opt"><option>-S</option> <group choice="plain"> <arg choice="plain"><option>a[uto]</option></arg> <arg choice="plain"><option>d[emand]</option></arg> </group> </arg> - <arg choice="opt"><option>-w</option></arg> + <arg choice="opt"><option>-e</option> <replaceable>source</replaceable></arg> + <arg choice="opt"><option>-W</option></arg> <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg> <arg choice="opt"><option>-s</option></arg> <arg choice="opt"><option>-o</option> <replaceable>options</replaceable></arg> @@ -147,14 +152,14 @@ PostgreSQL documentation <para> The <option>init</option> or <option>initdb</option> mode creates a new - <productname>PostgreSQL</productname> database cluster. A database - cluster is a collection of databases that are managed by a single + <productname>PostgreSQL</productname> database cluster, that is, + a collection of databases that will be managed by a single server instance. This mode invokes the <command>initdb</command> command. See <xref linkend="app-initdb"> for details. </para> <para> - In <option>start</option> mode, a new server is launched. The + <option>start</option> mode launches a new server. The server is started in the background, and its standard input is attached to <filename>/dev/null</filename> (or <literal>nul</> on Windows). On Unix-like systems, by default, the server's standard output and @@ -172,8 +177,8 @@ PostgreSQL documentation </para> <para> - In <option>stop</option> mode, the server that is running in - the specified data directory is shut down. Three different + <option>stop</option> mode shuts down the server that is running in + the specified data directory. Three different shutdown methods can be selected with the <option>-m</option> option. <quote>Smart</quote> mode waits for all active clients to disconnect and any online backup to finish. @@ -183,60 +188,63 @@ PostgreSQL documentation will terminate an online backup in progress. All active transactions are rolled back and clients are forcibly disconnected, then the server is shut down. <quote>Immediate</quote> mode will abort - all server processes immediately, without a clean shutdown. - This will lead to a crash-recovery run on the next restart. + all server processes immediately, without a clean shutdown. This choice + will lead to a crash-recovery cycle during the next server start. </para> <para> <option>restart</option> mode effectively executes a stop followed by a start. This allows changing the <command>postgres</command> - command-line options. <option>restart</option> might fail if - relative paths specified were specified on the command-line during - server start. + command-line options, or changing configuration-file options that + cannot be changed without restarting the server. + If relative paths were used on the command line during server + start, <option>restart</option> might fail unless + <application>pg_ctl</application> is executed in the same current + directory as it was during server start. </para> <para> <option>reload</option> mode simply sends the - <command>postgres</command> process a <systemitem>SIGHUP</> + <command>postgres</command> server process a <systemitem>SIGHUP</> signal, causing it to reread its configuration files (<filename>postgresql.conf</filename>, - <filename>pg_hba.conf</filename>, etc.). This allows changing of - configuration-file options that do not require a complete restart + <filename>pg_hba.conf</filename>, etc.). This allows changing + configuration-file options that do not require a full server restart to take effect. </para> <para> <option>status</option> mode checks whether a server is running in - the specified data directory. If it is, the <acronym>PID</acronym> - and the command line options that were used to invoke it are - displayed. If the server is not running, the process returns an - exit status of 3. If an accessible data directory is not specified, - the process returns an exit status of 4. + the specified data directory. If it is, the server's <acronym>PID</acronym> + and the command line options that were used to invoke it are displayed. + If the server is not running, <application>pg_ctl</application> returns + an exit status of 3. If an accessible data directory is not + specified, <application>pg_ctl</application> returns an exit status of 4. </para> <para> - In <option>promote</option> mode, the standby server that is - running in the specified data directory is commanded to exit - recovery and begin read-write operations. + <option>promote</option> mode commands the standby server that is + running in the specified data directory to end standby mode + and begin read-write operations. </para> <para> - <option>kill</option> mode allows you to send a signal to a specified - process. This is particularly valuable for <productname>Microsoft Windows</> - which does not have a <application>kill</> command. Use - <literal>--help</> to see a list of supported signal names. + <option>kill</option> mode sends a signal to a specified process. + This is primarily valuable on <productname>Microsoft Windows</> + which does not have a built-in <application>kill</> command. Use + <literal>--help</> to see a list of supported signal names. </para> <para> - <option>register</option> mode allows you to register a system service - on <productname>Microsoft Windows</>. The <option>-S</option> option - allows selection of service start type, either <quote>auto</quote> (start - service automatically on system startup) or <quote>demand</quote> (start - service on demand). + <option>register</option> mode registers the <productname>PostgreSQL</> + server as a system service on <productname>Microsoft Windows</>. + The <option>-S</option> option allows selection of service start type, + either <quote>auto</quote> (start service automatically on system startup) + or <quote>demand</quote> (start service on demand). </para> <para> - <option>unregister</option> mode allows you to unregister a system service + <option>unregister</option> mode unregisters a system service on <productname>Microsoft Windows</>. This undoes the effects of the <option>register</option> command. </para> @@ -249,7 +257,7 @@ PostgreSQL documentation <varlistentry> <term><option>-c</option></term> - <term><option>--core-file</option></term> + <term><option>--core-files</option></term> <listitem> <para> Attempt to allow server crashes to produce core files, on platforms @@ -263,11 +271,11 @@ PostgreSQL documentation <varlistentry> <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term> - <term><option>--pgdata <replaceable class="parameter">datadir</replaceable></option></term> + <term><option>--pgdata=<replaceable class="parameter">datadir</replaceable></option></term> <listitem> <para> Specifies the file system location of the database configuration files. If - this is omitted, the environment variable + this option is omitted, the environment variable <envar>PGDATA</envar> is used. </para> </listitem> @@ -275,7 +283,7 @@ PostgreSQL documentation <varlistentry> <term><option>-l <replaceable class="parameter">filename</replaceable></option></term> - <term><option>--log <replaceable class="parameter">filename</replaceable></option></term> + <term><option>--log=<replaceable class="parameter">filename</replaceable></option></term> <listitem> <para> Append the server log output to @@ -288,42 +296,48 @@ PostgreSQL documentation <varlistentry> <term><option>-m <replaceable class="parameter">mode</replaceable></option></term> - <term><option>--mode <replaceable class="parameter">mode</replaceable></option></term> + <term><option>--mode=<replaceable class="parameter">mode</replaceable></option></term> <listitem> <para> Specifies the shutdown mode. <replaceable>mode</replaceable> can be <literal>smart</literal>, <literal>fast</literal>, or <literal>immediate</literal>, or the first letter of one of - these three. If this is omitted, <literal>fast</literal> is used. + these three. If this option is omitted, <literal>fast</literal> is + the default. </para> </listitem> </varlistentry> <varlistentry> <term><option>-o <replaceable class="parameter">options</replaceable></option></term> + <term><option>--options=<replaceable class="parameter">options</replaceable></option></term> <listitem> <para> Specifies options to be passed directly to the - <command>postgres</command> command; multiple - option invocations are appended. + <command>postgres</command> command. + <option>-o</> can be specified multiple times, with all the given + options being passed through. </para> <para> - The options should usually be surrounded by single or double - quotes to ensure that they are passed through as a group. + The <replaceable>options</> should usually be surrounded by single or + double quotes to ensure that they are passed through as a group. </para> </listitem> </varlistentry> <varlistentry> <term><option>-o <replaceable class="parameter">initdb-options</replaceable></option></term> + <term><option>--options=<replaceable class="parameter">initdb-options</replaceable></option></term> <listitem> <para> Specifies options to be passed directly to the <command>initdb</command> command. + <option>-o</> can be specified multiple times, with all the given + options being passed through. </para> <para> - The options should usually be surrounded by single or double - quotes to ensure that they are passed through as a group. + The <replaceable>options</> should usually be surrounded by single or + double quotes to ensure that they are passed through as a group. </para> </listitem> </varlistentry> @@ -375,14 +389,14 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-t</option></term> - <term><option>--timeout</option></term> + <term><option>-t <replaceable class="parameter">seconds</replaceable></option></term> + <term><option>--timeout=<replaceable class="parameter">seconds</replaceable></option></term> <listitem> <para> - The maximum number of seconds to wait when waiting for startup or - shutdown to complete. Defaults to the value of the - <envar>PGCTLTIMEOUT</> environment variable or, if not set, to 60 - seconds. + Specifies the maximum number of seconds to wait when waiting for an + operation to complete (see option <option>-w</option>). Defaults to + the value of the <envar>PGCTLTIMEOUT</> environment variable or, if + not set, to 60 seconds. </para> </listitem> </varlistentry> @@ -399,15 +413,20 @@ PostgreSQL documentation <varlistentry> <term><option>-w</option></term> + <term><option>--wait</option></term> <listitem> <para> - Wait for the startup or shutdown to complete. - Waiting is the default option for shutdowns, but not startups. + Wait for the operation to complete. This is supported for the + modes <literal>start</literal>, <literal>stop</literal>, + <literal>restart</literal>, <literal>promote</literal>, + and <literal>register</literal>, and is the default for those modes. + </para> + + <para> When waiting for startup, <command>pg_ctl</command> repeatedly attempts to connect to the server. When waiting for shutdown, <command>pg_ctl</command> waits for the server to remove its <acronym>PID</acronym> file. - This option allows the entry of an <acronym>SSL</> passphrase on startup. <command>pg_ctl</command> returns an exit code based on the success of the startup or shutdown. </para> @@ -416,10 +435,23 @@ PostgreSQL documentation <varlistentry> <term><option>-W</option></term> + <term><option>--no-wait</option></term> <listitem> <para> - Do not wait for startup or shutdown to complete. This is the - default for start and restart modes. + Do not wait for the operation to complete. This is the opposite of + the option <option>-w</option>. + </para> + + <para> + If waiting is disabled, the requested action is triggered, but there + is no feedback about its success. In that case, the server log file + or an external monitoring system would have to be used to check the + progress and success of the operation. + </para> + + <para> + In prior releases of PostgreSQL, this was the default except for + the <literal>stop</literal> mode. </para> </listitem> </varlistentry> @@ -436,6 +468,11 @@ PostgreSQL documentation </varlistentry> </variablelist> + <para> + If an option is specified that is valid, but not relevant to the selected + operating mode, <application>pg_ctl</application> ignores it. + </para> + <refsect2 id="app-pg-ctl-windows-options"> <title>Options for Windows</title> @@ -447,11 +484,12 @@ PostgreSQL documentation Name of the event source for <application>pg_ctl</application> to use for logging to the event log when running as a Windows service. The default is <literal>PostgreSQL</literal>. Note that this only controls - the logging from <application>pg_ctl</application> itself; once + messages sent from <application>pg_ctl</application> itself; once started, the server will use the event source specified - by <xref linkend="guc-event-source">. Should the server fail during - early startup, it might also log using the default event - source <literal>PostgreSQL</literal>. + by its <xref linkend="guc-event-source"> parameter. Should the server + fail very early in startup, before that parameter has been set, + it might also log using the default event + source name <literal>PostgreSQL</literal>. </para> </listitem> </varlistentry> @@ -460,8 +498,9 @@ PostgreSQL documentation <term><option>-N <replaceable class="parameter">servicename</replaceable></option></term> <listitem> <para> - Name of the system service to register. The name will be used + Name of the system service to register. This name will be used as both the service name and the display name. + The default is <literal>PostgreSQL</literal>. </para> </listitem> </varlistentry> @@ -470,7 +509,7 @@ PostgreSQL documentation <term><option>-P <replaceable class="parameter">password</replaceable></option></term> <listitem> <para> - Password for the user to start the service. + Password for the user to run the service as. </para> </listitem> </varlistentry> @@ -479,10 +518,10 @@ PostgreSQL documentation <term><option>-S <replaceable class="parameter">start-type</replaceable></option></term> <listitem> <para> - Start type of the system service to register. start-type can + Start type of the system service. <replaceable>start-type</> can be <literal>auto</literal>, or <literal>demand</literal>, or - the first letter of one of these two. If this is omitted, - <literal>auto</literal> is used. + the first letter of one of these two. If this option is omitted, + <literal>auto</literal> is the default. </para> </listitem> </varlistentry> @@ -491,7 +530,7 @@ PostgreSQL documentation <term><option>-U <replaceable class="parameter">username</replaceable></option></term> <listitem> <para> - User name for the user to start the service. For domain users, use the + User name for the user to run the service as. For domain users, use the format <literal>DOMAIN\username</literal>. </para> </listitem> @@ -530,11 +569,21 @@ PostgreSQL documentation </variablelist> <para> + Most <command>pg_ctl</command> modes require knowing the data directory + location; therefore, the <option>-D</> option is required + unless <envar>PGDATA</envar> is set. + </para> + + <para> <command>pg_ctl</command>, like most other <productname>PostgreSQL</> utilities, also uses the environment variables supported by <application>libpq</> (see <xref linkend="libpq-envars">). - For additional server variables, see <xref linkend="app-postgres">. + </para> + + <para> + For additional variables that affect the server, + see <xref linkend="app-postgres">. </para> <para> @@ -552,9 +601,8 @@ PostgreSQL documentation <listitem> <para> - The existence of this file in the data directory is used to help - <application>pg_ctl</application> determine if the server is - currently running. + <application>pg_ctl</application> examines this file in the data + directory to determine whether the server is currently running. </para> </listitem> </varlistentry> @@ -584,17 +632,10 @@ PostgreSQL documentation <title>Starting the Server</title> <para> - To start the server: -<screen> -<prompt>$</prompt> <userinput>pg_ctl start</userinput> -</screen> - </para> - - <para> To start the server, waiting until the server is accepting connections: <screen> -<prompt>$</prompt> <userinput>pg_ctl -w start</userinput> +<prompt>$</prompt> <userinput>pg_ctl start</userinput> </screen> </para> @@ -616,7 +657,7 @@ PostgreSQL documentation The <option>-m</option> option allows control over <emphasis>how</emphasis> the server shuts down: <screen> -<prompt>$</prompt> <userinput>pg_ctl stop -m fast</userinput> +<prompt>$</prompt> <userinput>pg_ctl stop -m smart</userinput> </screen></para> </refsect2> @@ -625,24 +666,17 @@ PostgreSQL documentation <para> Restarting the server is almost equivalent to stopping the - server and starting it again, - except that <command>pg_ctl</command> saves and reuses the command line options that - were passed to the previously running instance. To restart - the server in the simplest form, use: + server and starting it again, except that by default, + <command>pg_ctl</command> saves and reuses the command line options that + were passed to the previously-running instance. To restart + the server using the same options as before, use: <screen> <prompt>$</prompt> <userinput>pg_ctl restart</userinput> </screen> </para> <para> - To restart the server, - waiting for it to shut down and restart: -<screen> -<prompt>$</prompt> <userinput>pg_ctl -w restart</userinput> -</screen> - </para> - - <para> + But if <option>-o</> is specified, that replaces any previous options. To restart using port 5433, disabling <function>fsync</> upon restart: <screen> <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput> @@ -662,7 +696,7 @@ pg_ctl: server is running (PID: 13718) /usr/local/pgsql/bin/postgres "-D" "/usr/local/pgsql/data" "-p" "5433" "-B" "128" </computeroutput> </screen> - This is the command line that would be invoked in restart mode. + The second line is the command that would be invoked in restart mode. </para> </refsect2> </refsect1> diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index be1b684082..bb0bf5d566 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -138,8 +138,27 @@ PostgreSQL documentation <para> Include large objects in the dump. This is the default behavior except when <option>--schema</>, <option>--table</>, or - <option>--schema-only</> is specified, so the <option>-b</> - switch is only useful to add large objects to selective dumps. + <option>--schema-only</> is specified. The <option>-b</> + switch is therefore only useful to add large objects to dumps + where a specific schema or table has been requested. Note that + blobs are considered data and therefore will be included when + --data-only is used, but not when --schema-only is. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-B</></term> + <term><option>--no-blobs</></term> + <listitem> + <para> + Exclude large objects in the dump. + </para> + + <para> + When both <option>-b</> and <option>-B</> are given, the behavior + is to output large objects, when data is being dumped, see the + <option>-b</> documentation. </para> </listitem> </varlistentry> @@ -699,6 +718,11 @@ PostgreSQL documentation to dump the parts of the contents of the table that they have access to. </para> + <para> + Note that if you use this option currently, you probably also want + the dump be in <command>INSERT</command> format, as the + <command>COPY FROM</command> during restore does not support row security. + </para> </listitem> </varlistentry> @@ -758,10 +782,18 @@ PostgreSQL documentation the dump. Instead fail if unable to lock a table within the specified <replaceable class="parameter">timeout</>. The timeout may be specified in any of the formats accepted by <command>SET - statement_timeout</>. (Allowed values vary depending on the server + statement_timeout</>. (Allowed formats vary depending on the server version you are dumping from, but an integer number of milliseconds - is accepted by all versions since 7.3. This option is ignored when - dumping from a pre-7.3 server.) + is accepted by all versions.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-publications</option></term> + <listitem> + <para> + Do not dump publications. </para> </listitem> </varlistentry> @@ -776,6 +808,15 @@ PostgreSQL documentation </varlistentry> <varlistentry> + <term><option>--no-subscriptions</option></term> + <listitem> + <para> + Do not dump subscriptions. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>--no-synchronized-snapshots</></term> <listitem> <para> @@ -816,6 +857,20 @@ PostgreSQL documentation </varlistentry> <varlistentry> + <term><option>--no-sync</option></term> + <listitem> + <para> + By default, <command>pg_dump</command> will wait for all files + to be written safely to disk. This option causes + <command>pg_dump</command> to return without waiting, which is + faster, but means that a subsequent operating system crash can leave + the dump corrupt. Generally, this option is useful for testing + but should not be used when dumping data from production installation. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>--quote-all-identifiers</></term> <listitem> <para> @@ -1172,7 +1227,7 @@ CREATE DATABASE foo WITH TEMPLATE template0; <productname>PostgreSQL</> server versions newer than <application>pg_dump</>'s version. <application>pg_dump</> can also dump from <productname>PostgreSQL</> servers older than its own version. - (Currently, servers back to version 7.0 are supported.) + (Currently, servers back to version 8.0 are supported.) However, <application>pg_dump</> cannot dump from <productname>PostgreSQL</> servers newer than its own major version; it will refuse to even try, rather than risk making an invalid dump. @@ -1185,6 +1240,19 @@ CREATE DATABASE foo WITH TEMPLATE template0; in cross-version cases, as it can prevent problems arising from varying reserved-word lists in different <productname>PostgreSQL</> versions. </para> + + <para> + When dumping logical replication subscriptions, + <application>pg_dump</application> will generate <command>CREATE + SUBSCRIPTION</command> commands that use the <literal>NOCONNECT</literal> + option, so that restoring the subscription does not make remote connections + for creating a replication slot or for initial table copy. That way, the + dump can be restored without requiring network access to the remote + servers. It is then up to the user to reactivate the subscriptions in a + suitable way. If the involved hosts have changed, the connection + information might have to be changed. It might also be appropriate to + truncate the target tables before initiating a new full table copy. + </para> </refsect1> <refsect1 id="pg-dump-examples"> diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml index 97168a0815..b45e813486 100644 --- a/doc/src/sgml/ref/pg_dumpall.sgml +++ b/doc/src/sgml/ref/pg_dumpall.sgml @@ -333,6 +333,28 @@ PostgreSQL documentation </varlistentry> <varlistentry> + <term><option>--no-role-passwords</option></term> + <listitem> + <para> + Do not dump passwords for roles. When restored, roles will have a NULL + password and authentication will always fail until the password is reset. + Since password values aren't needed when this option is specified we + use the catalog view pg_roles in preference to pg_authid, since access + to pg_authid may be restricted by security policy. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-publications</option></term> + <listitem> + <para> + Do not dump publications. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>--no-security-labels</option></term> <listitem> <para> @@ -342,6 +364,29 @@ PostgreSQL documentation </varlistentry> <varlistentry> + <term><option>--no-subscriptions</option></term> + <listitem> + <para> + Do not dump subscriptions. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-sync</option></term> + <listitem> + <para> + By default, <command>pg_dumpall</command> will wait for all files + to be written safely to disk. This option causes + <command>pg_dumpall</command> to return without waiting, which is + faster, but means that a subsequent operating system crash can leave + the dump corrupt. Generally, this option is useful for testing + but should not be used when dumping data from production installation. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>--no-tablespaces</option></term> <listitem> <para> diff --git a/doc/src/sgml/ref/pg_receivexlog.sgml b/doc/src/sgml/ref/pg_receivewal.sgml index bfa055b58b..a17082bb11 100644 --- a/doc/src/sgml/ref/pg_receivexlog.sgml +++ b/doc/src/sgml/ref/pg_receivewal.sgml @@ -1,27 +1,27 @@ <!-- -doc/src/sgml/ref/pg_receivexlog.sgml +doc/src/sgml/ref/pg_receivewal.sgml PostgreSQL documentation --> -<refentry id="app-pgreceivexlog"> - <indexterm zone="app-pgreceivexlog"> - <primary>pg_receivexlog</primary> +<refentry id="app-pgreceivewal"> + <indexterm zone="app-pgreceivewal"> + <primary>pg_receivewal</primary> </indexterm> <refmeta> - <refentrytitle>pg_receivexlog</refentrytitle> + <refentrytitle>pg_receivewal</refentrytitle> <manvolnum>1</manvolnum> <refmiscinfo>Application</refmiscinfo> </refmeta> <refnamediv> - <refname>pg_receivexlog</refname> - <refpurpose>stream transaction logs from a <productname>PostgreSQL</productname> server</refpurpose> + <refname>pg_receivewal</refname> + <refpurpose>stream write-ahead logs from a <productname>PostgreSQL</productname> server</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> - <command>pg_receivexlog</command> + <command>pg_receivewal</command> <arg rep="repeat"><replaceable>option</></arg> </cmdsynopsis> </refsynopsisdiv> @@ -31,8 +31,8 @@ PostgreSQL documentation Description </title> <para> - <application>pg_receivexlog</application> is used to stream the transaction log - from a running <productname>PostgreSQL</productname> cluster. The transaction + <application>pg_receivewal</application> is used to stream the write-ahead log + from a running <productname>PostgreSQL</productname> cluster. The write-ahead log is streamed using the streaming replication protocol, and is written to a local directory of files. This directory can be used as the archive location for doing a restore using point-in-time recovery (see @@ -40,23 +40,23 @@ PostgreSQL documentation </para> <para> - <application>pg_receivexlog</application> streams the transaction + <application>pg_receivewal</application> streams the write-ahead log in real time as it's being generated on the server, and does not wait for segments to complete like <xref linkend="guc-archive-command"> does. For this reason, it is not necessary to set <xref linkend="guc-archive-timeout"> when using - <application>pg_receivexlog</application>. + <application>pg_receivewal</application>. </para> <para> - Unlike the WAL receiver of a PostgreSQL standby server, <application>pg_receivexlog</> + Unlike the WAL receiver of a PostgreSQL standby server, <application>pg_receivewal</> by default flushes WAL data only when a WAL file is closed. The option <option>--synchronous</> must be specified to flush WAL data in real time. </para> <para> - The transaction log is streamed over a regular + The write-ahead log is streamed over a regular <productname>PostgreSQL</productname> connection and uses the replication protocol. The connection must be made with a superuser or a user having <literal>REPLICATION</literal> permissions (see @@ -68,7 +68,7 @@ PostgreSQL documentation <para> If the connection is lost, or if it cannot be initially established, - with a non-fatal error, <application>pg_receivexlog</application> will + with a non-fatal error, <application>pg_receivewal</application> will retry the connection indefinitely, and reestablish streaming as soon as possible. To avoid this behavior, use the <literal>-n</literal> parameter. @@ -132,9 +132,9 @@ PostgreSQL documentation <term><option>--slot=<replaceable class="parameter">slotname</replaceable></option></term> <listitem> <para> - Require <application>pg_receivexlog</application> to use an existing + Require <application>pg_receivewal</application> to use an existing replication slot (see <xref linkend="streaming-replication-slots">). - When this option is used, <application>pg_receivexlog</> will report + When this option is used, <application>pg_receivewal</> will report a flush position to the server, indicating when each segment has been synchronized to disk so that the server can remove that segment if it is not otherwise needed. @@ -142,7 +142,7 @@ PostgreSQL documentation <para> When the replication client - of <application>pg_receivexlog</application> is configured on the + of <application>pg_receivewal</application> is configured on the server as a synchronous standby, then using a replication slot will report the flush position to the server, but only when a WAL file is closed. Therefore, that configuration will cause transactions on the @@ -164,7 +164,7 @@ PostgreSQL documentation <para> This option should be specified if the replication client - of <application>pg_receivexlog</application> is configured on the + of <application>pg_receivewal</application> is configured on the server as a synchronous standby, to ensure that timely feedback is sent to the server. </para> @@ -180,6 +180,19 @@ PostgreSQL documentation </para> </listitem> </varlistentry> + + <varlistentry> + <term><option>-Z <replaceable class="parameter">level</replaceable></option></term> + <term><option>--compress=<replaceable class="parameter">level</replaceable></option></term> + <listitem> + <para> + Enables gzip compression of write-ahead logs, and specifies the + compression level (0 through 9, 0 being no compression and 9 being best + compression). The suffix <filename>.gz</filename> will + automatically be added to all filenames. + </para> + </listitem> + </varlistentry> </variablelist> <para> @@ -196,7 +209,7 @@ PostgreSQL documentation </para> <para> The option is called <literal>--dbname</> for consistency with other - client applications, but because <application>pg_receivexlog</application> + client applications, but because <application>pg_receivewal</application> doesn't connect to any particular database in the cluster, database name in the connection string will be ignored. </para> @@ -260,15 +273,15 @@ PostgreSQL documentation <term><option>--password</option></term> <listitem> <para> - Force <application>pg_receivexlog</application> to prompt for a + Force <application>pg_receivewal</application> to prompt for a password before connecting to a database. </para> <para> This option is never essential, since - <application>pg_receivexlog</application> will automatically prompt + <application>pg_receivewal</application> will automatically prompt for a password if the server demands password authentication. - However, <application>pg_receivexlog</application> will waste a + However, <application>pg_receivewal</application> will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing <option>-W</> to avoid the extra connection attempt. @@ -279,7 +292,7 @@ PostgreSQL documentation </para> <para> - <application>pg_receivexlog</application> can perform one of the two + <application>pg_receivewal</application> can perform one of the two following actions in order to control physical replication slots: <variablelist> @@ -314,7 +327,7 @@ PostgreSQL documentation <term><option>--version</></term> <listitem> <para> - Print the <application>pg_receivexlog</application> version and exit. + Print the <application>pg_receivewal</application> version and exit. </para> </listitem> </varlistentry> @@ -324,7 +337,7 @@ PostgreSQL documentation <term><option>--help</></term> <listitem> <para> - Show help about <application>pg_receivexlog</application> command line + Show help about <application>pg_receivewal</application> command line arguments, and exit. </para> </listitem> @@ -350,10 +363,10 @@ PostgreSQL documentation <title>Notes</title> <para> - When using <application>pg_receivexlog</application> instead of + When using <application>pg_receivewal</application> instead of <xref linkend="guc-archive-command"> as the main WAL backup method, it is strongly recommended to use replication slots. Otherwise, the server is - free to recycle or remove transaction log files before they are backed up, + free to recycle or remove write-ahead log files before they are backed up, because it does not have any information, either from <xref linkend="guc-archive-command"> or the replication slots, about how far the WAL stream has been archived. Note, however, that a @@ -367,11 +380,11 @@ PostgreSQL documentation <title>Examples</title> <para> - To stream the transaction log from the server at + To stream the write-ahead log from the server at <literal>mydbserver</literal> and store it in the local directory <filename>/usr/local/pgsql/archive</filename>: <screen> -<prompt>$</prompt> <userinput>pg_receivexlog -h mydbserver -D /usr/local/pgsql/archive</userinput> +<prompt>$</prompt> <userinput>pg_receivewal -h mydbserver -D /usr/local/pgsql/archive</userinput> </screen></para> </refsect1> diff --git a/doc/src/sgml/ref/pg_recvlogical.sgml b/doc/src/sgml/ref/pg_recvlogical.sgml index b35881f2b9..eaea94df8b 100644 --- a/doc/src/sgml/ref/pg_recvlogical.sgml +++ b/doc/src/sgml/ref/pg_recvlogical.sgml @@ -35,9 +35,17 @@ PostgreSQL documentation <para> It creates a replication-mode connection, so it is subject to the same - constraints as <xref linkend="app-pgreceivexlog">, plus those for logical + constraints as <xref linkend="app-pgreceivewal">, plus those for logical replication (see <xref linkend="logicaldecoding">). </para> + + <para> + <command>pg_recvlogical</> has no equivalent to the logical decoding + SQL interface's peek and get modes. It sends replay confirmations for + data lazily as it receives it and on clean exit. To examine pending data on + a slot without consuming it, use + <link linkend="functions-replication"><function>pg_logical_slot_peek_changes</></>. + </para> </refsect1> <refsect1> @@ -155,6 +163,32 @@ PostgreSQL documentation </varlistentry> <varlistentry> + <term><option>-E <replaceable>lsn</replaceable></option></term> + <term><option>--endpos=<replaceable>lsn</replaceable></option></term> + <listitem> + <para> + In <option>--start</option> mode, automatically stop replication + and exit with normal exit status 0 when receiving reaches the + specified LSN. If specified when not in <option>--start</option> + mode, an error is raised. + </para> + + <para> + If there's a record with LSN exactly equal to <replaceable>lsn</>, + the record will be output. + </para> + + <para> + The <option>--endpos</option> option is not aware of transaction + boundaries and may truncate output partway through a transaction. + Any partially output transaction will not be consumed and will be + replayed again when the slot is next read from. Individual messages + are never truncated. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>--if-not-exists</option></term> <listitem> <para> @@ -204,7 +238,7 @@ PostgreSQL documentation <listitem> <para> This option has the same effect as the option of the same name - in <xref linkend="app-pgreceivexlog">. See the description there. + in <xref linkend="app-pgreceivewal">. See the description there. </para> </listitem> </varlistentry> @@ -377,7 +411,7 @@ PostgreSQL documentation <title>See Also</title> <simplelist type="inline"> - <member><xref linkend="app-pgreceivexlog"></member> + <member><xref linkend="app-pgreceivewal"></member> </simplelist> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/pg_resetxlog.sgml b/doc/src/sgml/ref/pg_resetwal.sgml index e72021764a..a23fe18b72 100644 --- a/doc/src/sgml/ref/pg_resetxlog.sgml +++ b/doc/src/sgml/ref/pg_resetwal.sgml @@ -1,27 +1,27 @@ <!-- -doc/src/sgml/ref/pg_resetxlog.sgml +doc/src/sgml/ref/pg_resetwal.sgml PostgreSQL documentation --> -<refentry id="APP-PGRESETXLOG"> - <indexterm zone="app-pgresetxlog"> - <primary>pg_resetxlog</primary> +<refentry id="APP-PGRESETWAL"> + <indexterm zone="app-pgresetwal"> + <primary>pg_resetwal</primary> </indexterm> <refmeta> - <refentrytitle><application>pg_resetxlog</application></refentrytitle> + <refentrytitle><application>pg_resetwal</application></refentrytitle> <manvolnum>1</manvolnum> <refmiscinfo>Application</refmiscinfo> </refmeta> <refnamediv> - <refname>pg_resetxlog</refname> + <refname>pg_resetwal</refname> <refpurpose>reset the write-ahead log and other control information of a <productname>PostgreSQL</productname> database cluster</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> - <command>pg_resetxlog</command> + <command>pg_resetwal</command> <arg choice="opt"><option>-f</option></arg> <arg choice="opt"><option>-n</option></arg> <arg rep="repeat"><replaceable>option</replaceable></arg> @@ -29,10 +29,10 @@ PostgreSQL documentation </cmdsynopsis> </refsynopsisdiv> - <refsect1 id="R1-APP-PGRESETXLOG-1"> + <refsect1 id="R1-APP-PGRESETWAL-1"> <title>Description</title> <para> - <command>pg_resetxlog</command> clears the write-ahead log (WAL) and + <command>pg_resetwal</command> clears the write-ahead log (WAL) and optionally resets some other control information stored in the <filename>pg_control</> file. This function is sometimes needed if these files have become corrupted. It should be used only as a @@ -51,12 +51,12 @@ PostgreSQL documentation This utility can only be run by the user who installed the server, because it requires read/write access to the data directory. For safety reasons, you must specify the data directory on the command line. - <command>pg_resetxlog</command> does not use the environment variable + <command>pg_resetwal</command> does not use the environment variable <envar>PGDATA</>. </para> <para> - If <command>pg_resetxlog</command> complains that it cannot determine + If <command>pg_resetwal</command> complains that it cannot determine valid data for <filename>pg_control</>, you can force it to proceed anyway by specifying the <option>-f</> (force) option. In this case plausible values will be substituted for the missing data. Most of the fields can be @@ -80,7 +80,7 @@ PostgreSQL documentation <term><option>-f</option></term> <listitem> <para> - Force <command>pg_resetxlog</command> to proceed even if it cannot determine + Force <command>pg_resetwal</command> to proceed even if it cannot determine valid data for <filename>pg_control</>, as explained above. </para> </listitem> @@ -91,10 +91,10 @@ PostgreSQL documentation <listitem> <para> The <option>-n</> (no operation) option instructs - <command>pg_resetxlog</command> to print the values reconstructed from + <command>pg_resetwal</command> to print the values reconstructed from <filename>pg_control</> and values about to be changed, and then exit without modifying anything. This is mainly a debugging tool, but can be - useful as a sanity check before allowing <command>pg_resetxlog</command> + useful as a sanity check before allowing <command>pg_resetwal</command> to proceed for real. </para> </listitem> @@ -115,7 +115,7 @@ PostgreSQL documentation <para> The following options are only needed when - <command>pg_resetxlog</command> is unable to determine appropriate values + <command>pg_resetwal</command> is unable to determine appropriate values by reading <filename>pg_control</>. Safe values can be determined as described below. For values that take numeric arguments, hexadecimal values can be specified by using the prefix <literal>0x</literal>. @@ -152,7 +152,7 @@ PostgreSQL documentation <para> The transaction ID epoch is not actually stored anywhere in the database - except in the field that is set by <command>pg_resetxlog</command>, + except in the field that is set by <command>pg_resetwal</command>, so any value will work so far as the database itself is concerned. You might need to adjust this value to ensure that replication systems such as <application>Slony-I</> and @@ -164,7 +164,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-l</option> <replaceable class="parameter">xlogfile</replaceable></term> + <term><option>-l</option> <replaceable class="parameter">walfile</replaceable></term> <listitem> <para> Manually set the WAL starting address. @@ -173,22 +173,22 @@ PostgreSQL documentation <para> The WAL starting address should be larger than any WAL segment file name currently existing in - the directory <filename>pg_xlog</> under the data directory. + the directory <filename>pg_wal</> under the data directory. These names are also in hexadecimal and have three parts. The first part is the <quote>timeline ID</> and should usually be kept the same. For example, if <filename>00000001000000320000004A</> is the - largest entry in <filename>pg_xlog</>, use <literal>-l 00000001000000320000004B</> or higher. + largest entry in <filename>pg_wal</>, use <literal>-l 00000001000000320000004B</> or higher. </para> <note> <para> - <command>pg_resetxlog</command> itself looks at the files in - <filename>pg_xlog</> and chooses a default <option>-l</> setting + <command>pg_resetwal</command> itself looks at the files in + <filename>pg_wal</> and chooses a default <option>-l</> setting beyond the last existing file name. Therefore, manual adjustment of <option>-l</> should only be needed if you are aware of WAL segment - files that are not currently present in <filename>pg_xlog</>, such as + files that are not currently present in <filename>pg_wal</>, such as entries in an offline archive; or if the contents of - <filename>pg_xlog</> have been lost entirely. + <filename>pg_wal</> have been lost entirely. </para> </note> </listitem> @@ -256,12 +256,12 @@ PostgreSQL documentation <para> A safe value can be determined by looking for the numerically largest - file name in the directory <filename>pg_clog</> under the data directory, + file name in the directory <filename>pg_xact</> under the data directory, adding one, and then multiplying by 1048576 (0x100000). Note that the file names are in hexadecimal. It is usually easiest to specify the option value in hexadecimal too. For example, if <filename>0011</> is the largest entry - in <filename>pg_clog</>, <literal>-x 0x1200000</> will work (five + in <filename>pg_xact</>, <literal>-x 0x1200000</> will work (five trailing zeroes provide the proper multiplier). </para> </listitem> @@ -274,16 +274,21 @@ PostgreSQL documentation <para> This command must not be used when the server is - running. <command>pg_resetxlog</command> will refuse to start up if + running. <command>pg_resetwal</command> will refuse to start up if it finds a server lock file in the data directory. If the server crashed then a lock file might have been left behind; in that case you can remove the lock file to allow - <command>pg_resetxlog</command> to run. But before you do + <command>pg_resetwal</command> to run. But before you do so, make doubly certain that there is no server process still alive. </para> <para> - In <productname>Postgres-XL</>, <command>pg_resetxlog</command> + <command>pg_resetwal</command> works only with servers of the same + major version. + </para> + + <para> + In <productname>Postgres-XL</>, <command>pg_resetwal</command> will only run locally for Coordinators and Datanodes. You should run it for each Coordinator or Datanode manually. </para> diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index c9069193af..f623cc04d2 100644 --- a/doc/src/sgml/ref/pg_restore.sgml +++ b/doc/src/sgml/ref/pg_restore.sgml @@ -302,7 +302,7 @@ </varlistentry> <varlistentry> - <term><option>-n <replaceable class="parameter">namespace</replaceable></option></term> + <term><option>-n <replaceable class="parameter">schema</replaceable></option></term> <term><option>--schema=<replaceable class="parameter">schema</replaceable></option></term> <listitem> <para> @@ -315,6 +315,22 @@ </varlistentry> <varlistentry> + <term><option>-N <replaceable class="parameter">schema</replaceable></option></term> + <term><option>--exclude-schema=<replaceable class="parameter">schema</replaceable></option></term> + <listitem> + <para> + Do not restore objects that are in the named schema. Multiple schemas + to be excluded may be specified with multiple <option>-N</> switches. + </para> + + <para> + When both <option>-n</> and <option>-N</> are given for the same + schema name, the <option>-N</> switch wins and the schema is excluded. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>-O</option></term> <term><option>--no-owner</option></term> <listitem> @@ -527,7 +543,7 @@ <para> Note that this option currently also requires the dump be in <command>INSERT</command> - format, as <command>COPY TO</command> does not support row security. + format, as <command>COPY FROM</command> does not support row security. </para> </listitem> </varlistentry> @@ -566,6 +582,16 @@ </varlistentry> <varlistentry> + <term><option>--no-publications</option></term> + <listitem> + <para> + Do not output commands to restore publications, even if the archive + contains them. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>--no-security-labels</option></term> <listitem> <para> @@ -576,6 +602,16 @@ </varlistentry> <varlistentry> + <term><option>--no-subscriptions</option></term> + <listitem> + <para> + Do not output commands to restore subscriptions, even if the archive + contains them. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><option>--no-tablespaces</option></term> <listitem> <para> diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml index 42ebfbfdef..d5430d4324 100644 --- a/doc/src/sgml/ref/pg_rewind.sgml +++ b/doc/src/sgml/ref/pg_rewind.sgml @@ -61,14 +61,14 @@ PostgreSQL documentation <para> <application>pg_rewind</> examines the timeline histories of the source and target clusters to determine the point where they diverged, and - expects to find WAL in the target cluster's <filename>pg_xlog</> directory + expects to find WAL in the target cluster's <filename>pg_wal</> directory reaching all the way back to the point of divergence. The point of divergence can be found either on the target timeline, the source timeline, or their common ancestor. In the typical failover scenario where the target cluster was shut down soon after the divergence, this is not a problem, but if the target cluster ran for a long time after the divergence, the old WAL files might no longer be present. In that case, they can be manually - copied from the WAL archive to the <filename>pg_xlog</> directory, or + copied from the WAL archive to the <filename>pg_wal</> directory, or fetched on startup by configuring <filename>recovery.conf</>. The use of <application>pg_rewind</> is not limited to failover, e.g. a standby server can be promoted, run some write transactions, and then rewinded @@ -229,7 +229,7 @@ PostgreSQL documentation </step> <step> <para> - Copy all other files such as <filename>pg_clog</filename> and + Copy all other files such as <filename>pg_xact</filename> and configuration files from the source cluster to the target cluster (everything except the relation files). </para> diff --git a/doc/src/sgml/ref/pg_xlogdump.sgml b/doc/src/sgml/ref/pg_waldump.sgml index 296f1acc24..cff88a4c1e 100644 --- a/doc/src/sgml/ref/pg_xlogdump.sgml +++ b/doc/src/sgml/ref/pg_waldump.sgml @@ -1,27 +1,27 @@ <!-- -doc/src/sgml/ref/pg_xlogdump.sgml +doc/src/sgml/ref/pg_waldump.sgml PostgreSQL documentation --> -<refentry id="pgxlogdump"> - <indexterm zone="pgxlogdump"> - <primary>pg_xlogdump</primary> +<refentry id="pgwaldump"> + <indexterm zone="pgwaldump"> + <primary>pg_waldump</primary> </indexterm> <refmeta> - <refentrytitle><application>pg_xlogdump</application></refentrytitle> + <refentrytitle><application>pg_waldump</application></refentrytitle> <manvolnum>1</manvolnum> <refmiscinfo>Application</refmiscinfo> </refmeta> <refnamediv> - <refname>pg_xlogdump</refname> + <refname>pg_waldump</refname> <refpurpose>display a human-readable rendering of the write-ahead log of a <productname>PostgreSQL</productname> database cluster</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> - <command>pg_xlogdump</command> + <command>pg_waldump</command> <arg rep="repeat" choice="opt"><option>option</option></arg> <arg choice="opt"><option>startseg</option> <arg choice="opt"><option>endseg</option></arg> @@ -29,10 +29,10 @@ PostgreSQL documentation </cmdsynopsis> </refsynopsisdiv> - <refsect1 id="R1-APP-PGXLOGDUMP-1"> + <refsect1 id="R1-APP-PGWALDUMP-1"> <title>Description</title> <para> - <command>pg_xlogdump</command> displays the write-ahead log (WAL) and is mainly + <command>pg_waldump</command> displays the write-ahead log (WAL) and is mainly useful for debugging or educational purposes. </para> @@ -85,7 +85,7 @@ PostgreSQL documentation <term><option>--end=<replaceable>end</replaceable></option></term> <listitem> <para> - Stop reading at the specified log position, instead of reading to the + Stop reading at the specified WAL location, instead of reading to the end of the log stream. </para> </listitem> @@ -117,9 +117,12 @@ PostgreSQL documentation <term><option>--path=<replaceable>path</replaceable></option></term> <listitem> <para> - Directory in which to find log segment files. The default is to search - for them in the <literal>pg_xlog</literal> subdirectory of the current - directory. + Specifies a directory to search for log segment files or a + directory with a <literal>pg_wal</literal> subdirectory that + contains such files. The default is to search in the current + directory, the <literal>pg_wal</literal> subdirectory of the + current directory, and the <literal>pg_wal</literal> subdirectory + of <envar>PGDATA</envar>. </para> </listitem> </varlistentry> @@ -141,7 +144,7 @@ PostgreSQL documentation <term><option>--start=<replaceable>start</replaceable></option></term> <listitem> <para> - Log position at which to start reading. The default is to start reading + WAL location at which to start reading. The default is to start reading the first valid log record found in the earliest file found. </para> </listitem> @@ -153,7 +156,7 @@ PostgreSQL documentation <listitem> <para> Timeline from which to read log records. The default is to use the - value in <literal>startseg</>, if that is specified; otherwise, the + value in <replaceable>startseg</>, if that is specified; otherwise, the default is 1. </para> </listitem> @@ -164,7 +167,7 @@ PostgreSQL documentation <term><option>--version</></term> <listitem> <para> - Print the <application>pg_xlogdump</application> version and exit. + Print the <application>pg_waldump</application> version and exit. </para> </listitem> </varlistentry> @@ -196,7 +199,7 @@ PostgreSQL documentation <term><option>--help</></term> <listitem> <para> - Show help about <application>pg_xlogdump</application> command line + Show help about <application>pg_waldump</application> command line arguments, and exit. </para> </listitem> @@ -217,7 +220,7 @@ PostgreSQL documentation </para> <para> - <application>pg_xlogdump</> cannot read WAL files with suffix + <application>pg_waldump</> cannot read WAL files with suffix <literal>.partial</>. If those files need to be read, <literal>.partial</> suffix needs to be removed from the file name. </para> diff --git a/doc/src/sgml/ref/pgarchivecleanup.sgml b/doc/src/sgml/ref/pgarchivecleanup.sgml index 60a7fc4e6b..abe01bef4f 100644 --- a/doc/src/sgml/ref/pgarchivecleanup.sgml +++ b/doc/src/sgml/ref/pgarchivecleanup.sgml @@ -122,7 +122,7 @@ pg_archivecleanup: removing file "archive/00000001000000370000000E" <term><option>-x</option> <replaceable>extension</></term> <listitem> <para> - When using the program as a standalone utility, provide an extension + Provide an extension that will be stripped from all file names before deciding if they should be deleted. This is typically useful for cleaning up archives that have been compressed during storage, and therefore have had an diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml index c386a95148..c3c8371c69 100644 --- a/doc/src/sgml/ref/pgbench.sgml +++ b/doc/src/sgml/ref/pgbench.sgml @@ -368,7 +368,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <term><option>--log</option></term> <listitem> <para> - Write the time taken by each transaction to a log file. + Write information about each transaction to a log file. See below for details. </para> </listitem> @@ -446,7 +446,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <term><option>--progress=</option><replaceable>sec</></term> <listitem> <para> - Show progress report every <literal>sec</> seconds. The report + Show progress report every <replaceable>sec</> seconds. The report includes the time since the beginning of the run, the tps since the last report, and the transaction latency average and standard deviation since the last report. Under throttling (<option>-R</>), @@ -597,13 +597,9 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <term><option>--aggregate-interval=<replaceable>seconds</></option></term> <listitem> <para> - Length of aggregation interval (in seconds). May be used only together - with <application>-l</application> - with this option, the log contains - per-interval summary (number of transactions, min/max latency and two - additional fields useful for variance estimation). - </para> - <para> - This option is not currently supported on Windows. + Length of aggregation interval (in seconds). May be used only + with <option>-l</option> option. With this option, the log contains + per-interval summary data, as described below. </para> </listitem> </varlistentry> @@ -639,6 +635,16 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </listitem> </varlistentry> + <varlistentry> + <term><option>--log-prefix=<replaceable>prefix</></option></term> + <listitem> + <para> + Set the filename prefix for the log files created by + <option>--log</>. The default is <literal>pgbench_log</>. + </para> + </listitem> + </varlistentry> + </variablelist> </para> @@ -828,7 +834,8 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <para> Script file meta commands begin with a backslash (<literal>\</>) and - extend to the end of the line. + normally extend to the end of the line, although they can be continued + to additional lines by writing backslash-return. Arguments to a meta command are separated by white space. These meta commands are supported: </para> @@ -857,7 +864,8 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> Examples: <programlisting> \set ntellers 10 * :scale -\set aid (1021 * random(1, 100000 * :scale)) % (100000 * :scale) + 1 +\set aid (1021 * random(1, 100000 * :scale)) % \ + (100000 * :scale) + 1 </programlisting></para> </listitem> </varlistentry> @@ -1143,16 +1151,20 @@ END; <title>Per-Transaction Logging</title> <para> - With the <option>-l</> option but without the <option>--aggregate-interval</option>, - <application>pgbench</> writes the time taken by each transaction + With the <option>-l</> option (but without + the <option>--aggregate-interval</option> option), + <application>pgbench</> writes information about each transaction to a log file. The log file will be named - <filename>pgbench_log.<replaceable>nnn</></filename>, where - <replaceable>nnn</> is the PID of the <application>pgbench</application> process. - If the <option>-j</> option is 2 or higher, creating multiple worker - threads, each will have its own log file. The first worker will use the - same name for its log file as in the standard single worker case. + <filename><replaceable>prefix</>.<replaceable>nnn</></filename>, + where <replaceable>prefix</> defaults to <literal>pgbench_log</>, and + <replaceable>nnn</> is the PID of the + <application>pgbench</application> process. + The prefix can be changed by using the <option>--log-prefix</> option. + If the <option>-j</> option is 2 or higher, so that there are multiple + worker threads, each will have its own log file. The first worker will + use the same name for its log file as in the standard single worker case. The additional log files for the other workers will be named - <filename>pgbench_log.<replaceable>nnn</>.<replaceable>mmm</></filename>, + <filename><replaceable>prefix</>.<replaceable>nnn</>.<replaceable>mmm</></filename>, where <replaceable>mmm</> is a sequential number for each worker starting with 1. </para> @@ -1161,18 +1173,22 @@ END; The format of the log is: <synopsis> -<replaceable>client_id</> <replaceable>transaction_no</> <replaceable>time</> <replaceable>script_no</> <replaceable>time_epoch</> <replaceable>time_us</> <optional><replaceable>schedule_lag</replaceable></optional> +<replaceable>client_id</> <replaceable>transaction_no</> <replaceable>time</> <replaceable>script_no</> <replaceable>time_epoch</> <replaceable>time_us</> <optional> <replaceable>schedule_lag</replaceable> </optional> </synopsis> - where <replaceable>time</> is the total elapsed transaction time in microseconds, + where + <replaceable>client_id</> indicates which client session ran the transaction, + <replaceable>transaction_no</> counts how many transactions have been + run by that session, + <replaceable>time</> is the total elapsed transaction time in microseconds, <replaceable>script_no</> identifies which script file was used (useful when multiple scripts were specified with <option>-f</> or <option>-b</>), and <replaceable>time_epoch</>/<replaceable>time_us</> are a - Unix epoch format time stamp and an offset + Unix-epoch time stamp and an offset in microseconds (suitable for creating an ISO 8601 time stamp with fractional seconds) showing when the transaction completed. - Field <replaceable>schedule_lag</> is the difference between the + The <replaceable>schedule_lag</> field is the difference between the transaction's scheduled start time, and the time it actually started, in microseconds. It is only present when the <option>--rate</> option is used. When both <option>--rate</> and <option>--latency-limit</> are used, @@ -1181,7 +1197,7 @@ END; </para> <para> - Here is a snippet of the log file generated: + Here is a snippet of a log file generated in a single-client run: <screen> 0 199 2241 0 1175850568 995598 0 200 2465 0 1175850568 998079 @@ -1189,7 +1205,8 @@ END; 0 202 2038 0 1175850569 2663 </screen> - Another example with --rate=100 and --latency-limit=5 (note the additional + Another example with <literal>--rate=100</> + and <literal>--latency-limit=5</> (note the additional <replaceable>schedule_lag</> column): <screen> 0 81 4621 0 1412881037 912698 3005 @@ -1216,32 +1233,41 @@ END; <title>Aggregated Logging</title> <para> - With the <option>--aggregate-interval</option> option, the logs use a bit different format: + With the <option>--aggregate-interval</option> option, a different + format is used for the log files: <synopsis> -<replaceable>interval_start</> <replaceable>num_of_transactions</> <replaceable>latency_sum</> <replaceable>latency_2_sum</> <replaceable>min_latency</> <replaceable>max_latency</> <optional><replaceable>lag_sum</> <replaceable>lag_2_sum</> <replaceable>min_lag</> <replaceable>max_lag</> <optional><replaceable>skipped_transactions</></optional></optional> +<replaceable>interval_start</> <replaceable>num_transactions</> <replaceable>sum_latency</> <replaceable>sum_latency_2</> <replaceable>min_latency</> <replaceable>max_latency</> <optional> <replaceable>sum_lag</> <replaceable>sum_lag_2</> <replaceable>min_lag</> <replaceable>max_lag</> <optional> <replaceable>skipped</> </optional> </optional> </synopsis> - where <replaceable>interval_start</> is the start of the interval (Unix epoch - format time stamp), <replaceable>num_of_transactions</> is the number of transactions - within the interval, <replaceable>latency_sum</replaceable> is a sum of latencies - (so you can compute average latency easily). The following two fields are useful - for variance estimation - <replaceable>latency_sum</> is a sum of latencies and - <replaceable>latency_2_sum</> is a sum of 2nd powers of latencies. The next two - fields are <replaceable>min_latency</> - a minimum latency within the interval, and - <replaceable>max_latency</> - maximum latency within the interval. A transaction is - counted into the interval when it was committed. The fields in the end, - <replaceable>lag_sum</>, <replaceable>lag_2_sum</>, <replaceable>min_lag</>, + where + <replaceable>interval_start</> is the start of the interval (as a Unix + epoch time stamp), + <replaceable>num_transactions</> is the number of transactions + within the interval, + <replaceable>sum_latency</replaceable> is the sum of the transaction + latencies within the interval, + <replaceable>sum_latency_2</replaceable> is the sum of squares of the + transaction latencies within the interval, + <replaceable>min_latency</> is the minimum latency within the interval, + and + <replaceable>max_latency</> is the maximum latency within the interval. + The next fields, + <replaceable>sum_lag</>, <replaceable>sum_lag_2</>, <replaceable>min_lag</>, and <replaceable>max_lag</>, are only present if the <option>--rate</> - option is used. The very last one, <replaceable>skipped_transactions</>, - is only present if the option <option>--latency-limit</> is present, too. - They are calculated from the time each transaction had to wait for the + option is used. + They provide statistics about the time each transaction had to wait for the previous one to finish, i.e. the difference between each transaction's scheduled start time and the time it actually started. + The very last field, <replaceable>skipped</>, + is only present if the <option>--latency-limit</> option is used, too. + It counts the number of transactions skipped because they would have + started too late. + Each transaction is counted in the interval when it was committed. </para> <para> - Here is example output: + Here is some example output: <screen> 1345828501 5601 1542744 483552416 61 2573 1345828503 7884 1979812 565806736 60 1479 @@ -1251,9 +1277,9 @@ END; </screen></para> <para> - Notice that while the plain (unaggregated) log file contains a reference - to the custom script files, the aggregated log does not. Therefore if - you need per script data, you need to aggregate the data on your own. + Notice that while the plain (unaggregated) log file shows which script + was used for each transaction, the aggregated log does not. Therefore if + you need per-script data, you need to aggregate the data on your own. </para> </refsect2> diff --git a/doc/src/sgml/ref/pgtestfsync.sgml b/doc/src/sgml/ref/pgtestfsync.sgml index 6e134c75df..467d6e647a 100644 --- a/doc/src/sgml/ref/pgtestfsync.sgml +++ b/doc/src/sgml/ref/pgtestfsync.sgml @@ -34,7 +34,7 @@ problem. However, differences shown by <application>pg_test_fsync</application> might not make any significant difference in real database throughput, especially since many database servers - are not speed-limited by their transaction logs. + are not speed-limited by their write-ahead logs. <application>pg_test_fsync</application> reports average file sync operation time in microseconds for each <literal>wal_sync_method</literal>, which can also be used to inform efforts to optimize the value of <xref linkend="guc-commit-delay">. @@ -57,8 +57,8 @@ <para> Specifies the file name to write test data in. This file should be in the same file system that the - <filename>pg_xlog</> directory is or will be placed in. - (<filename>pg_xlog</> contains the <acronym>WAL</> files.) + <filename>pg_wal</> directory is or will be placed in. + (<filename>pg_wal</> contains the <acronym>WAL</> files.) The default is <filename>pg_test_fsync.out</> in the current directory. </para> diff --git a/doc/src/sgml/ref/pgtesttiming.sgml b/doc/src/sgml/ref/pgtesttiming.sgml index f07a0600ff..e3539cf764 100644 --- a/doc/src/sgml/ref/pgtesttiming.sgml +++ b/doc/src/sgml/ref/pgtesttiming.sgml @@ -96,9 +96,9 @@ <screen> Testing timing overhead for 3 seconds. -Per loop time including overhead: 35.96 nsec +Per loop time including overhead: 35.96 ns Histogram of timing durations: -< usec % of total count + < us % of total count 1 96.40465 80435604 2 3.59518 2999652 4 0.00015 126 @@ -109,9 +109,9 @@ Histogram of timing durations: <para> Note that different units are used for the per loop time than the - histogram. The loop can have resolution within a few nanoseconds (nsec), + histogram. The loop can have resolution within a few nanoseconds (ns), while the individual timing calls can only resolve down to one microsecond - (usec). + (us). </para> </refsect2> @@ -157,9 +157,9 @@ EXPLAIN ANALYZE SELECT COUNT(*) FROM t; tsc hpet acpi_pm # echo acpi_pm > /sys/devices/system/clocksource/clocksource0/current_clocksource # pg_test_timing -Per loop time including overhead: 722.92 nsec +Per loop time including overhead: 722.92 ns Histogram of timing durations: -< usec % of total count + < us % of total count 1 27.84870 1155682 2 72.05956 2990371 4 0.07810 3241 @@ -170,7 +170,7 @@ Histogram of timing durations: <para> In this configuration, the sample <command>EXPLAIN ANALYZE</command> above - takes 115.9 ms. That's 1061 nsec of timing overhead, again a small multiple + 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 @@ -211,7 +211,7 @@ $ pg_test_timing Testing timing overhead for 3 seconds. Per timing duration including loop overhead: 97.75 ns Histogram of timing durations: -< usec % of total count + < us % of total count 1 90.23734 27694571 2 9.75277 2993204 4 0.00981 3010 diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index d534b4e33d..9e3e98865c 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -279,7 +279,8 @@ make prefix=/usr/local/pgsql.new install into the new cluster, e.g. <filename>pgcrypto.so</filename>, whether they are from <filename>contrib</filename> or some other source. Do not install the schema definitions, e.g. - <filename>pgcrypto.sql</>, because these will be upgraded from the old cluster. + <command>CREATE EXTENSION pgcrypto</>, because these will be upgraded + from the old cluster. Also, any custom full text search files (dictionary, synonym, thesaurus, stop words) must also be copied to the new cluster. </para> @@ -341,8 +342,8 @@ NET STOP postgresql-9.0 Always run the <application>pg_upgrade</> binary of the new server, not the old one. <application>pg_upgrade</> requires the specification of the old and new cluster's data and executable (<filename>bin</>) directories. You can also specify - user and port values, and whether you want the data linked instead of - copied (the default). + user and port values, and whether you want the data files linked + instead of the default copy behavior. </para> <para> @@ -351,7 +352,7 @@ NET STOP postgresql-9.0 your old cluster once you start the new cluster after the upgrade. Link mode also requires that the old and new cluster data directories be in the - same file system. (Tablespaces and <filename>pg_xlog</> can be on + same file system. (Tablespaces and <filename>pg_wal</> can be on different file systems.) See <literal>pg_upgrade --help</> for a full list of options. </para> @@ -514,7 +515,7 @@ rsync --archive --delete --hard-links --size-only old_pgdata new_pgdata remote_d <para> If you have tablespaces, you will need to run a similar <application>rsync</> command for each tablespace directory. If you - have relocated <filename>pg_xlog</> outside the data directories, + have relocated <filename>pg_wal</> outside the data directories, <application>rsync</> must be run on those directories too. </para> </step> @@ -564,7 +565,7 @@ rsync --archive --delete --hard-links --size-only old_pgdata new_pgdata remote_d run using: <programlisting> -psql --username postgres --file script.sql postgres +psql --username=postgres --file=script.sql postgres </programlisting> The scripts can be run in any order and can be deleted once they have diff --git a/doc/src/sgml/ref/prepare.sgml b/doc/src/sgml/ref/prepare.sgml index 8efd51aaec..fea2196efe 100644 --- a/doc/src/sgml/ref/prepare.sgml +++ b/doc/src/sgml/ref/prepare.sgml @@ -73,7 +73,7 @@ PREPARE <replaceable class="PARAMETER">name</replaceable> [ ( <replaceable class Prepared statements potentially have the largest performance advantage when a single session is being used to execute a large number of similar statements. The performance difference will be particularly - significant if the statements are complex to plan or rewrite, e.g. + significant if the statements are complex to plan or rewrite, e.g. if the query involves a join of many tables or requires the application of several rules. If the statement is relatively simple to plan and rewrite but relatively expensive to execute, the diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index d9bce25f33..3b86612862 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -455,8 +455,8 @@ EOF any, by an equal sign on the command line. To unset a variable, leave off the equal sign. To set a variable with an empty value, use the equal sign but leave off the value. These assignments are - done during a very early stage of start-up, so variables reserved - for internal purposes might get overwritten later. + done during command line processing, so variables that reflect + connection state will get overwritten later. </para> </listitem> </varlistentry> @@ -770,17 +770,32 @@ testdb=> </para> <para> - Within an argument, text that is enclosed in backquotes - (<literal>`</literal>) is taken as a command line that is passed to the - shell. The output of the command (with any trailing newline removed) - replaces the backquoted text. - </para> - - <para> If an unquoted colon (<literal>:</literal>) followed by a <application>psql</> variable name appears within an argument, it is replaced by the variable's value, as described in <xref linkend="APP-PSQL-interpolation" endterm="APP-PSQL-interpolation-title">. + The forms <literal>:'<replaceable>variable_name</>'</literal> and + <literal>:"<replaceable>variable_name</>"</literal> described there + work as well. + </para> + + <para> + Within an argument, text that is enclosed in backquotes + (<literal>`</literal>) is taken as a command line that is passed to the + shell. The output of the command (with any trailing newline removed) + replaces the backquoted text. Within the text enclosed in backquotes, + no special quoting or other processing occurs, except that appearances + of <literal>:<replaceable>variable_name</></literal> where + <replaceable>variable_name</> is a <application>psql</> variable name + are replaced by the variable's value. Also, appearances of + <literal>:'<replaceable>variable_name</>'</literal> are replaced by the + variable's value suitably quoted to become a single shell command + argument. (The latter form is almost always preferable, unless you are + very sure of what is in the variable.) Because carriage return and line + feed characters cannot be safely quoted on all platforms, the + <literal>:'<replaceable>variable_name</>'</literal> form prints an + error message and does not substitute the variable value when such + characters appear in the value. </para> <para> @@ -809,6 +824,14 @@ testdb=> </para> <para> + Many of the meta-commands act on the <firstterm>current query buffer</>. + This is simply a buffer holding whatever SQL command text has been typed + but not yet sent to the server for execution. This will include previous + input lines as well as any text appearing before the meta-command on the + same line. + </para> + + <para> The following meta-commands are defined: <variablelist> @@ -830,7 +853,7 @@ testdb=> <para> Establishes a new connection to a <productname>PostgreSQL</> server. The connection parameters to use can be specified either - using a positional syntax, or using <literal>conninfo</> connection + using a positional syntax, or using <replaceable>conninfo</> connection strings as detailed in <xref linkend="libpq-connstring">. </para> @@ -838,7 +861,7 @@ testdb=> Where the command omits database name, user, host, or port, the new connection can reuse values from the previous connection. By default, values from the previous connection are reused except when processing - a <literal>conninfo</> string. Passing a first argument + a <replaceable>conninfo</> string. Passing a first argument of <literal>-reuse-previous=on</> or <literal>-reuse-previous=off</literal> overrides that default. When the command neither specifies nor reuses a particular parameter, @@ -966,8 +989,10 @@ testdb=> command. All options other than the data source/destination are as specified for <xref linkend="sql-copy">. Because of this, special parsing rules apply to the <command>\copy</> - command. In particular, <application>psql</>'s variable substitution - rules and backslash escapes do not apply. + meta-command. Unlike most other meta-commands, the entire remainder + of the line is always taken to be the arguments of <command>\copy</>, + and neither variable interpolation nor backquote expansion are + performed in the arguments. </para> <tip> @@ -1601,6 +1626,34 @@ testdb=> </varlistentry> <varlistentry> + <term><literal>\dRp[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term> + <listitem> + <para> + Lists replication publications. + If <replaceable class="parameter">pattern</replaceable> is + specified, only those publications whose names match the pattern are + listed. + If <literal>+</literal> is appended to the command name, the tables + associated with each publication are shown as well. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>\dRs[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term> + <listitem> + <para> + Lists replication subscriptions. + If <replaceable class="parameter">pattern</replaceable> is + specified, only those subscriptions whose names match the pattern are + listed. + If <literal>+</literal> is appended to the command name, additional + properties of the subscriptions are shown. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><literal>\dT[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term> <listitem> <para> @@ -1670,22 +1723,28 @@ testdb=> <listitem> <para> If <replaceable class="parameter">filename</replaceable> is - specified, the file is edited; after the editor exits, its - content is copied back to the query buffer. If no <replaceable + specified, the file is edited; after the editor exits, the file's + content is copied into the current query buffer. If no <replaceable class="parameter">filename</replaceable> is given, the current query buffer is copied to a temporary file which is then edited in the same + fashion. Or, if the current query buffer is empty, the most recently + executed query is copied to a temporary file and edited in the same fashion. </para> <para> - The new query buffer is then re-parsed according to the normal - rules of <application>psql</application>, where the whole buffer - is treated as a single line. (Thus you cannot make scripts this - way. Use <command>\i</command> for that.) This means that - if the query ends with (or contains) a semicolon, it is - immediately executed. Otherwise it will merely wait in the - query buffer; type semicolon or <literal>\g</> to send it, or - <literal>\r</> to cancel. + The new contents of the query buffer are then re-parsed according to + the normal rules of <application>psql</application>, treating the + whole buffer as a single line. Any complete queries are immediately + executed; that is, if the query buffer contains or ends with a + semicolon, everything up to that point is executed. Whatever remains + will wait in the query buffer; type semicolon or <literal>\g</> to + send it, or <literal>\r</> to cancel it by clearing the query buffer. + Treating the buffer as a single line primarily affects meta-commands: + whatever is in the buffer after a meta-command will be taken as + argument(s) to the meta-command, even if it spans multiple lines. + (Thus you cannot make meta-command-using scripts this way. + Use <command>\i</command> for that.) </para> <para> @@ -1763,6 +1822,13 @@ Tue Oct 26 21:40:57 CEST 1999 line of the file.) </para> + <para> + Unlike most other meta-commands, the entire remainder of the line is + always taken to be the argument(s) of <command>\ef</>, and neither + variable interpolation nor backquote expansion are performed in the + arguments. + </para> + <tip> <para> See under <xref linkend="app-psql-environment" @@ -1822,6 +1888,13 @@ Tue Oct 26 21:40:57 CEST 1999 If a line number is specified, <application>psql</application> will position the cursor on the specified line of the view definition. </para> + + <para> + Unlike most other meta-commands, the entire remainder of the line is + always taken to be the argument(s) of <command>\ev</>, and neither + variable interpolation nor backquote expansion are performed in the + arguments. + </para> </listitem> </varlistentry> @@ -1845,19 +1918,40 @@ Tue Oct 26 21:40:57 CEST 1999 <term><literal>\g [ |<replaceable class="parameter">command</replaceable> ]</literal></term> <listitem> <para> - Sends the current query input buffer to the server, and - optionally stores the query's output in <replaceable - class="parameter">filename</replaceable> or pipes the output - to the shell command <replaceable - class="parameter">command</replaceable>. The file or command is - written to only if the query successfully returns zero or more tuples, - not if the query fails or is a non-data-returning SQL command. + Sends the current query buffer to the server for execution. + If an argument is given, the query's output is written to the named + file or piped to the given shell command, instead of displaying it as + usual. The file or command is written to only if the query + successfully returns zero or more tuples, not if the query fails or + is a non-data-returning SQL command. </para> <para> - A bare <literal>\g</literal> is essentially equivalent to a semicolon. + If the current query buffer is empty, the most recently sent query is + re-executed instead. Except for that behavior, <literal>\g</literal> + without an argument is essentially equivalent to a semicolon. A <literal>\g</literal> with argument is a <quote>one-shot</quote> alternative to the <command>\o</command> command. </para> + <para> + If the argument begins with <literal>|</>, then the entire remainder + of the line is taken to be + the <replaceable class="parameter">command</replaceable> to execute, + and neither variable interpolation nor backquote expansion are + performed in it. The rest of the line is simply passed literally to + the shell. + </para> + </listitem> + </varlistentry> + + + <varlistentry> + <term><literal>\gx [ <replaceable class="parameter">filename</replaceable> ]</literal></term> + <term><literal>\gx [ |<replaceable class="parameter">command</replaceable> ]</literal></term> + <listitem> + <para> + <literal>\gx</literal> is equivalent to <literal>\g</literal>, but + forces expanded output mode for this query. See <literal>\x</literal>. + </para> </listitem> </varlistentry> @@ -1867,7 +1961,7 @@ Tue Oct 26 21:40:57 CEST 1999 <listitem> <para> - Sends the current query input buffer to the server, then treats + Sends the current query buffer to the server, then treats each column of each row of the query's output (if any) as a SQL statement to be executed. For example, to create an index on each column of <structname>my_table</>: @@ -1900,6 +1994,10 @@ CREATE INDEX timing, and other query execution features apply to each generated query as well. </para> + <para> + If the current query buffer is empty, the most recently sent query + is re-executed instead. + </para> </listitem> </varlistentry> @@ -1909,7 +2007,7 @@ CREATE INDEX <listitem> <para> - Sends the current query input buffer to the server and stores the + Sends the current query buffer to the server and stores the query's output into <application>psql</> variables (see <xref linkend="APP-PSQL-variables" endterm="APP-PSQL-variables-title">). The query to be executed must return exactly one row. Each column of @@ -1941,6 +2039,10 @@ hello 10 If the query fails or does not return one row, no variables are changed. </para> + <para> + If the current query buffer is empty, the most recently sent query + is re-executed instead. + </para> </listitem> </varlistentry> @@ -1957,6 +2059,13 @@ hello 10 <acronym>SQL</acronym> commands is shown. </para> + <para> + Unlike most other meta-commands, the entire remainder of the line is + always taken to be the argument(s) of <command>\help</>, and neither + variable interpolation nor backquote expansion are performed in the + arguments. + </para> + <note> <para> To simplify typing, commands that consists of several words do @@ -2024,6 +2133,95 @@ hello 10 <varlistentry> + <term><literal>\if</literal> <replaceable class="parameter">expression</replaceable></term> + <term><literal>\elif</literal> <replaceable class="parameter">expression</replaceable></term> + <term><literal>\else</literal></term> + <term><literal>\endif</literal></term> + <listitem> + <para> + This group of commands implements nestable conditional blocks. + A conditional block must begin with an <command>\if</command> and end + with an <command>\endif</command>. In between there may be any number + of <command>\elif</command> clauses, which may optionally be followed + by a single <command>\else</command> clause. Ordinary queries and + other types of backslash commands may (and usually do) appear between + the commands forming a conditional block. + </para> + <para> + The <command>\if</command> and <command>\elif</command> commands read + their argument(s) and evaluate them as a boolean expression. If the + expression yields <literal>true</literal> then processing continues + normally; otherwise, lines are skipped until a + matching <command>\elif</command>, <command>\else</command>, + or <command>\endif</command> is reached. Once + an <command>\if</command> or <command>\elif</command> test has + succeeded, the arguments of later <command>\elif</command> commands in + the same block are not evaluated but are treated as false. Lines + following an <command>\else</command> are processed only if no earlier + matching <command>\if</command> or <command>\elif</command> succeeded. + </para> + <para> + The <replaceable class="parameter">expression</replaceable> argument + of an <command>\if</command> or <command>\elif</command> command + is subject to variable interpolation and backquote expansion, just + like any other backslash command argument. After that it is evaluated + like the value of an on/off option variable. So a valid value + is any unambiguous case-insensitive match for one of: + <literal>true</literal>, <literal>false</literal>, <literal>1</literal>, + <literal>0</literal>, <literal>on</literal>, <literal>off</literal>, + <literal>yes</literal>, <literal>no</literal>. For example, + <literal>t</literal>, <literal>T</literal>, and <literal>tR</literal> + will all be considered to be <literal>true</literal>. + </para> + <para> + Expressions that do not properly evaluate to true or false will + generate a warning and be treated as false. + </para> + <para> + Lines being skipped are parsed normally to identify queries and + backslash commands, but queries are not sent to the server, and + backslash commands other than conditionals + (<command>\if</command>, <command>\elif</command>, + <command>\else</command>, <command>\endif</command>) are + ignored. Conditional commands are checked only for valid nesting. + Variable references in skipped lines are not expanded, and backquote + expansion is not performed either. + </para> + <para> + All the backslash commands of a given conditional block must appear in + the same source file. If EOF is reached on the main input file or an + <command>\include</command>-ed file before all local + <command>\if</command>-blocks have been closed, + then <application>psql</> will raise an error. + </para> + <para> + Here is an example: + </para> +<programlisting> +-- check for the existence of two separate records in the database and store +-- the results in separate psql variables +SELECT + EXISTS(SELECT 1 FROM customer WHERE customer_id = 123) as is_customer, + EXISTS(SELECT 1 FROM employee WHERE employee_id = 456) as is_employee +\gset +\if :is_customer + SELECT * FROM customer WHERE customer_id = 123; +\elif :is_employee + \echo 'is not a customer but is an employee' + SELECT * FROM employee WHERE employee_id = 456; +\else + \if yes + \echo 'not a customer or employee' + \else + \echo 'this will never print' + \endif +\endif +</programlisting> + </listitem> + </varlistentry> + + + <varlistentry> <term><literal>\l[+]</literal> or <literal>\list[+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term> <listitem> <para> @@ -2136,10 +2334,20 @@ lo_import 152801 specified, the query output is reset to the standard output. </para> - <para><quote>Query results</quote> includes all tables, command + <para> + If the argument begins with <literal>|</>, then the entire remainder + of the line is taken to be + the <replaceable class="parameter">command</replaceable> to execute, + and neither variable interpolation nor backquote expansion are + performed in it. The rest of the line is simply passed literally to + the shell. + </para> + + <para> + <quote>Query results</quote> includes all tables, command responses, and notices obtained from the database server, as well as output of various backslash commands that query the - database (such as <command>\d</command>), but not error + database (such as <command>\d</command>); but not error messages. </para> @@ -2158,6 +2366,8 @@ lo_import 152801 <listitem> <para> Print the current query buffer to the standard output. + If the current query buffer is empty, the most recently executed query + is printed instead. </para> </listitem> </varlistentry> @@ -2664,7 +2874,7 @@ lo_import 152801 class="parameter">name</replaceable> to <replaceable class="parameter">value</replaceable>, or if more than one value is given, to the concatenation of all of them. If only one - argument is given, the variable is set with an empty value. To + argument is given, the variable is set to an empty-string value. To unset a variable, use the <command>\unset</command> command. </para> @@ -2681,9 +2891,11 @@ lo_import 152801 </para> <para> - Although you are welcome to set any variable to anything you - want, <application>psql</application> treats several variables - as special. They are documented in the section about variables. + Certain variables are special, in that they + control <application>psql</application>'s behavior or are + automatically set to reflect connection state. These variables are + documented in <xref linkend="APP-PSQL-variables" + endterm="APP-PSQL-variables-title">, below. </para> <note> @@ -2736,6 +2948,13 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> output lines are numbered, with the first line of the function body being line 1. </para> + + <para> + Unlike most other meta-commands, the entire remainder of the line is + always taken to be the argument(s) of <command>\sf</>, and neither + variable interpolation nor backquote expansion are performed in the + arguments. + </para> </listitem> </varlistentry> @@ -2755,6 +2974,13 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> If <literal>+</literal> is appended to the command name, then the output lines are numbered from 1. </para> + + <para> + Unlike most other meta-commands, the entire remainder of the line is + always taken to be the argument(s) of <command>\sv</>, and neither + variable interpolation nor backquote expansion are performed in the + arguments. + </para> </listitem> </varlistentry> @@ -2789,8 +3015,11 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> <term><literal>\timing [ <replaceable class="parameter">on</replaceable> | <replaceable class="parameter">off</replaceable> ]</literal></term> <listitem> <para> - Without parameter, toggles a display of how long each SQL statement - takes, in milliseconds. With parameter, sets same. + With a parameter, turns displaying of how long each SQL statement + takes on or off. Without a parameter, toggles the display between + on and off. The display is in milliseconds; intervals longer than + 1 second are also shown in minutes:seconds format, with hours and + days fields added if needed. </para> </listitem> </varlistentry> @@ -2804,6 +3033,14 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> Unsets (deletes) the <application>psql</> variable <replaceable class="parameter">name</replaceable>. </para> + + <para> + Most variables that control <application>psql</application>'s behavior + cannot be unset; instead, an <literal>\unset</> command is interpreted + as setting them to their default values. + See <xref linkend="APP-PSQL-variables" + endterm="APP-PSQL-variables-title">, below. + </para> </listitem> </varlistentry> @@ -2813,9 +3050,20 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> <term><literal>\w</literal> or <literal>\write</literal> <literal>|</><replaceable class="parameter">command</replaceable></term> <listitem> <para> - Outputs the current query buffer to the file <replaceable + Writes the current query buffer to the file <replaceable class="parameter">filename</replaceable> or pipes it to the shell command <replaceable class="parameter">command</replaceable>. + If the current query buffer is empty, the most recently executed query + is written instead. + </para> + + <para> + If the argument begins with <literal>|</>, then the entire remainder + of the line is taken to be + the <replaceable class="parameter">command</replaceable> to execute, + and neither variable interpolation nor backquote expansion are + performed in it. The rest of the line is simply passed literally to + the shell. </para> </listitem> </varlistentry> @@ -2831,6 +3079,10 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> displayed with a header that includes the <literal>\pset title</> string (if any), the time as of query start, and the delay interval. </para> + <para> + If the current query buffer is empty, the most recently sent query + is re-executed instead. + </para> </listitem> </varlistentry> @@ -2869,11 +3121,17 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> <term><literal>\! [ <replaceable class="parameter">command</replaceable> ]</literal></term> <listitem> <para> - Escapes to a separate shell or executes the shell command - <replaceable class="parameter">command</replaceable>. The - arguments are not further interpreted; the shell will see them - as-is. In particular, the variable substitution rules and - backslash escapes do not apply. + With no argument, escapes to a sub-shell; <application>psql</> + resumes when the sub-shell exits. With an argument, executes the + shell command <replaceable class="parameter">command</replaceable>. + </para> + + <para> + Unlike most other meta-commands, the entire remainder of the line is + always taken to be the argument(s) of <command>\!</>, and neither + variable interpolation nor backquote expansion are performed in the + arguments. The rest of the line is simply passed literally to the + shell. </para> </listitem> </varlistentry> @@ -3022,7 +3280,7 @@ bar <para> If you call <command>\set</command> without a second argument, the - variable is set, with an empty string as value. To unset (i.e., delete) + variable is set to an empty-string value. To unset (i.e., delete) a variable, use the command <command>\unset</command>. To show the values of all variables, call <command>\set</command> without any argument. </para> @@ -3047,14 +3305,27 @@ bar by <application>psql</application>. They represent certain option settings that can be changed at run time by altering the value of the variable, or in some cases represent changeable state of - <application>psql</application>. Although - you can use these variables for other purposes, this is not - recommended, as the program behavior might grow really strange - really quickly. By convention, all specially treated variables' names + <application>psql</application>. + By convention, all specially treated variables' names consist of all upper-case ASCII letters (and possibly digits and underscores). To ensure maximum compatibility in the future, avoid - using such variable names for your own purposes. A list of all specially - treated variables follows. + using such variable names for your own purposes. + </para> + + <para> + Variables that control <application>psql</application>'s behavior + generally cannot be unset or set to invalid values. An <literal>\unset</> + command is allowed but is interpreted as setting the variable to its + default value. A <literal>\set</> command without a second argument is + interpreted as setting the variable to <literal>on</>, for control + variables that accept that value, and is rejected for others. Also, + control variables that accept the values <literal>on</> + and <literal>off</> will also accept other common spellings of Boolean + values, such as <literal>true</> and <literal>false</>. + </para> + + <para> + The specially treated variables are: </para> <variablelist> @@ -3124,7 +3395,7 @@ bar <para> The name of the database you are currently connected to. This is set every time you connect to a database (including program - start-up), but can be unset. + start-up), but can be changed or unset. </para> </listitem> </varlistentry> @@ -3139,12 +3410,11 @@ bar start-up, use the switch <option>-a</option>. If set to <literal>queries</literal>, <application>psql</application> prints each query to standard output - as it is sent to the server. The switch for this is + as it is sent to the server. The switch to select this behavior is <option>-e</option>. If set to <literal>errors</literal>, then only failed queries are displayed on standard error output. The switch - for this is <option>-b</option>. If unset, or if set to - <literal>none</literal> (or any other value than those above) then - no queries are displayed. + for this behavior is <option>-b</option>. If set to + <literal>none</literal> (the default), then no queries are displayed. </para> </listitem> </varlistentry> @@ -3159,8 +3429,9 @@ bar <productname>PostgreSQL</productname> internals and provide similar functionality in your own programs. (To select this behavior on program start-up, use the switch <option>-E</option>.) If you set - the variable to the value <literal>noexec</literal>, the queries are + this variable to the value <literal>noexec</literal>, the queries are just shown but are not actually sent to the server and executed. + The default value is <literal>off</>. </para> </listitem> </varlistentry> @@ -3170,6 +3441,9 @@ bar <listitem> <para> The current client character set encoding. + This is set every time you connect to a database (including + program start-up), and when you change the encoding + with <literal>\encoding</>, but it can be changed or unset. </para> </listitem> </varlistentry> @@ -3178,7 +3452,7 @@ bar <term><varname>FETCH_COUNT</varname></term> <listitem> <para> - If this variable is set to an integer value > 0, + If this variable is set to an integer value greater than zero, the results of <command>SELECT</command> queries are fetched and displayed in groups of that many rows, rather than the default behavior of collecting the entire result set before @@ -3189,6 +3463,7 @@ bar Keep in mind that when using this feature, a query might fail after having already displayed some rows. </para> + <tip> <para> Although you can use any output format with this feature, @@ -3210,9 +3485,8 @@ bar list. If set to a value of <literal>ignoredups</literal>, lines matching the previous history line are not entered. A value of <literal>ignoreboth</literal> combines the two options. If - unset, or if set to <literal>none</literal> (or any other value - than those above), all lines read in interactive mode are - saved on the history list. + set to <literal>none</literal> (the default), all lines + read in interactive mode are saved on the history list. </para> <note> <para> @@ -3227,8 +3501,12 @@ bar <term><varname>HISTFILE</varname></term> <listitem> <para> - The file name that will be used to store the history list. The default - value is <filename>~/.psql_history</filename>. For example, putting: + The file name that will be used to store the history list. If unset, + the file name is taken from the <envar>PSQL_HISTORY</envar> + environment variable. If that is not set either, the default + is <filename>~/.psql_history</filename>, + or <filename>%APPDATA%\postgresql\psql_history</filename> on Windows. + For example, putting: <programlisting> \set HISTFILE ~/.psql_history- :DBNAME </programlisting> @@ -3249,8 +3527,8 @@ bar <term><varname>HISTSIZE</varname></term> <listitem> <para> - The number of commands to store in the command history. The - default value is 500. + The maximum number of commands to store in the command history + (default 500). If set to a negative value, no limit is applied. </para> <note> <para> @@ -3267,7 +3545,7 @@ bar <para> The database server host you are currently connected to. This is set every time you connect to a database (including program - start-up), but can be unset. + start-up), but can be changed or unset. </para> </listitem> </varlistentry> @@ -3276,13 +3554,13 @@ bar <term><varname>IGNOREEOF</varname></term> <listitem> <para> - If unset, sending an <acronym>EOF</> character (usually + If set to 1 or less, sending an <acronym>EOF</> character (usually <keycombo action="simul"><keycap>Control</><keycap>D</></>) to an interactive session of <application>psql</application> - will terminate the application. If set to a numeric value, - that many <acronym>EOF</> characters are ignored before the - application terminates. If the variable is set but has no - numeric value, the default is 10. + will terminate the application. If set to a larger numeric value, + that many consecutive <acronym>EOF</> characters must be typed to + make an interactive session terminate. If the variable is set to a + non-numeric value, it is interpreted as 10. </para> <note> <para> @@ -3320,7 +3598,7 @@ bar generates an error, the error is ignored and the transaction continues. When set to <literal>interactive</>, such errors are only ignored in interactive sessions, and not when reading script - files. When unset or set to <literal>off</>, a statement in a + files. When set to <literal>off</> (the default), a statement in a transaction block that generates an error aborts the entire transaction. The error rollback mode works by issuing an implicit <command>SAVEPOINT</> for you, just before each command @@ -3355,7 +3633,7 @@ bar <para> The database server port to which you are currently connected. This is set every time you connect to a database (including - program start-up), but can be unset. + program start-up), but can be changed or unset. </para> </listitem> </varlistentry> @@ -3428,7 +3706,7 @@ bar <para> The database user you are currently connected as. This is set every time you connect to a database (including program - start-up), but can be unset. + start-up), but can be changed or unset. </para> </listitem> </varlistentry> @@ -3446,6 +3724,16 @@ bar </listitem> </varlistentry> + <varlistentry> + <term><varname>VERSION</varname></term> + <listitem> + <para> + This variable is set at program start-up to + reflect <application>psql</>'s version. It can be changed or unset. + </para> + </listitem> + </varlistentry> + </variablelist> </refsect3> @@ -3632,7 +3920,8 @@ testdb=> <userinput>INSERT INTO my_table VALUES (:'content');</userinput> <listitem> <para> In prompt 1 normally <literal>=</literal>, - but <literal>^</literal> if in single-line mode, + but <literal>@</literal> if the session is in an inactive branch of a + conditional block, or <literal>^</literal> if in single-line mode, or <literal>!</literal> if the session is disconnected from the database (which can happen if <command>\connect</command> fails). In prompt 2 <literal>%R</literal> is replaced by a character that @@ -3798,8 +4087,9 @@ $endif If the query results do not fit on the screen, they are piped through this command. Typical values are <literal>more</literal> or <literal>less</literal>. The default - is platform-dependent. The use of the pager can be disabled by - using the <command>\pset</command> command. + is platform-dependent. Use of the pager can be disabled by setting + <envar>PAGER</envar> to empty, or by using pager-related options of + the <command>\pset</command> command. </para> </listitem> </varlistentry> @@ -3974,6 +4264,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' </para> <para> The location of the history file can be set explicitly via + the <varname>HISTFILE</varname> <application>psql</> variable or the <envar>PSQL_HISTORY</envar> environment variable. </para> </listitem> @@ -4078,12 +4369,11 @@ CREATE TABLE Now look at the table definition again: <programlisting> testdb=> <userinput>\d my_table</userinput> - Table "my_table" - Attribute | Type | Modifier ------------+---------+-------------------- - first | integer | not null default 0 - second | text | - + Table "public.my_table" + Column | Type | Collation | Nullable | Default +--------+---------+-----------+----------+--------- + first | integer | | not null | 0 + second | text | | | </programlisting> Now we change the prompt to something more interesting: <programlisting> @@ -4170,7 +4460,7 @@ second | four with the <command>\crosstabview</command> command: <programlisting> testdb=> <userinput>SELECT first, second, first > 2 AS gt2 FROM my_table;</userinput> - first | second | ge2 + first | second | gt2 -------+--------+----- 1 | one | f 2 | two | f diff --git a/doc/src/sgml/ref/reindexdb.sgml b/doc/src/sgml/ref/reindexdb.sgml index 713efc099b..e4721d8113 100644 --- a/doc/src/sgml/ref/reindexdb.sgml +++ b/doc/src/sgml/ref/reindexdb.sgml @@ -24,7 +24,7 @@ PostgreSQL documentation <command>reindexdb</command> <arg rep="repeat"><replaceable>connection-option</replaceable></arg> <arg rep="repeat"><replaceable>option</replaceable></arg> - + <arg choice="plain" rep="repeat"> <arg choice="opt"> <group choice="plain"> @@ -396,7 +396,7 @@ PostgreSQL documentation To reindex the table <literal>foo</literal> and the index <literal>bar</literal> in a database named <literal>abcd</literal>: <screen> -<prompt>$ </prompt><userinput>reindexdb --table foo --index bar abcd</userinput> +<prompt>$ </prompt><userinput>reindexdb --table=foo --index=bar abcd</userinput> </screen></para> </refsect1> diff --git a/doc/src/sgml/ref/revoke.sgml b/doc/src/sgml/ref/revoke.sgml index fc00129620..ce532543f0 100644 --- a/doc/src/sgml/ref/revoke.sgml +++ b/doc/src/sgml/ref/revoke.sgml @@ -70,7 +70,7 @@ REVOKE [ GRANT OPTION FOR ] REVOKE [ GRANT OPTION FOR ] { EXECUTE | ALL [ PRIVILEGES ] } - ON { FUNCTION <replaceable>function_name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">arg_name</replaceable> ] <replaceable class="parameter">arg_type</replaceable> [, ...] ] ) [, ...] + ON { FUNCTION <replaceable>function_name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">arg_name</replaceable> ] <replaceable class="parameter">arg_type</replaceable> [, ...] ] ) ] [, ...] | ALL FUNCTIONS IN SCHEMA <replaceable>schema_name</replaceable> [, ...] } FROM { [ GROUP ] <replaceable class="PARAMETER">role_name</replaceable> | PUBLIC } [, ...] [ CASCADE | RESTRICT ] diff --git a/doc/src/sgml/ref/security_label.sgml b/doc/src/sgml/ref/security_label.sgml index 998fe3b7c0..aa8be473bd 100644 --- a/doc/src/sgml/ref/security_label.sgml +++ b/doc/src/sgml/ref/security_label.sgml @@ -30,13 +30,15 @@ SECURITY LABEL [ FOR <replaceable class="PARAMETER">provider</replaceable> ] ON DOMAIN <replaceable class="PARAMETER">object_name</replaceable> | EVENT TRIGGER <replaceable class="PARAMETER">object_name</replaceable> | FOREIGN TABLE <replaceable class="PARAMETER">object_name</replaceable> - FUNCTION <replaceable class="PARAMETER">function_name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) | + FUNCTION <replaceable class="PARAMETER">function_name</replaceable> [ ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) ] | LARGE OBJECT <replaceable class="PARAMETER">large_object_oid</replaceable> | MATERIALIZED VIEW <replaceable class="PARAMETER">object_name</replaceable> | [ PROCEDURAL ] LANGUAGE <replaceable class="PARAMETER">object_name</replaceable> | + PUBLICATION <replaceable class="PARAMETER">object_name</replaceable> | ROLE <replaceable class="PARAMETER">object_name</replaceable> | SCHEMA <replaceable class="PARAMETER">object_name</replaceable> | SEQUENCE <replaceable class="PARAMETER">object_name</replaceable> | + SUBSCRIPTION <replaceable class="PARAMETER">object_name</replaceable> | TABLESPACE <replaceable class="PARAMETER">object_name</replaceable> | TYPE <replaceable class="PARAMETER">object_name</replaceable> | VIEW <replaceable class="PARAMETER">object_name</replaceable> diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml index c4bd8fed44..211e4c320c 100644 --- a/doc/src/sgml/ref/select.sgml +++ b/doc/src/sgml/ref/select.sgml @@ -391,7 +391,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] not been changed meanwhile. But different seed values will usually produce different samples. If <literal>REPEATABLE</literal> is not given then a new random - sample is selected for each query. + sample is selected for each query, based upon a system-generated seed. Note that some add-on sampling methods do not accept <literal>REPEATABLE</literal>, and will always produce new samples on each use. diff --git a/doc/src/sgml/ref/set_role.sgml b/doc/src/sgml/ref/set_role.sgml index aff3792199..a97ceabcff 100644 --- a/doc/src/sgml/ref/set_role.sgml +++ b/doc/src/sgml/ref/set_role.sgml @@ -127,7 +127,7 @@ SELECT SESSION_USER, CURRENT_USER; <para> <productname>PostgreSQL</productname> - allows identifier syntax (<literal>"rolename"</literal>), while + allows identifier syntax (<literal>"<replaceable>rolename</>"</literal>), while the SQL standard requires the role name to be written as a string literal. SQL does not allow this command during a transaction; <productname>PostgreSQL</productname> does not make this diff --git a/doc/src/sgml/ref/set_session_auth.sgml b/doc/src/sgml/ref/set_session_auth.sgml index 4ac2128950..96d279aaf9 100644 --- a/doc/src/sgml/ref/set_session_auth.sgml +++ b/doc/src/sgml/ref/set_session_auth.sgml @@ -101,7 +101,7 @@ SELECT SESSION_USER, CURRENT_USER; The SQL standard allows some other expressions to appear in place of the literal <replaceable>user_name</replaceable>, but these options are not important in practice. <productname>PostgreSQL</productname> - allows identifier syntax (<literal>"username"</literal>), which SQL + allows identifier syntax (<literal>"<replaceable>username</>"</literal>), which SQL does not. SQL does not allow this command during a transaction; <productname>PostgreSQL</productname> does not make this restriction because there is no reason to. diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml index a78e47c095..e9c8a03a63 100644 --- a/doc/src/sgml/ref/truncate.sgml +++ b/doc/src/sgml/ref/truncate.sgml @@ -220,4 +220,12 @@ TRUNCATE othertable CASCADE; considered and compared with other implementations if necessary. </para> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-delete"></member> + </simplelist> + </refsect1> </refentry> diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml index 992d4d19d2..b84fd93a0e 100644 --- a/doc/src/sgml/ref/update.sgml +++ b/doc/src/sgml/ref/update.sgml @@ -24,7 +24,7 @@ PostgreSQL documentation [ WITH [ RECURSIVE ] <replaceable class="parameter">with_query</replaceable> [, ...] ] UPDATE [ ONLY ] <replaceable class="PARAMETER">table_name</replaceable> [ * ] [ [ AS ] <replaceable class="parameter">alias</replaceable> ] SET { <replaceable class="PARAMETER">column_name</replaceable> = { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } | - ( <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> ) } [, ...] [ FROM <replaceable class="PARAMETER">from_list</replaceable> ] @@ -285,6 +285,14 @@ UPDATE <replaceable class="parameter">count</replaceable> sub-selects is safer, though often harder to read and slower than using a join. </para> + + <para> + In the case of a partitioned table, updating a row might cause it to no + longer satisfy the partition constraint. Since there is no provision to + move the row to the partition appropriate to the new value of its + partitioning key, an error will occur in this case. This can also happen + when updating a partition directly. + </para> </refsect1> <refsect1> @@ -426,12 +434,12 @@ UPDATE films SET kind = 'Dramatic' WHERE CURRENT OF c_films; <para> According to the standard, the source value for a parenthesized sub-list of - column names can be any row-valued expression yielding the correct number - of columns. <productname>PostgreSQL</productname> only allows the source - value to be a parenthesized list of expressions (a row constructor) or a - sub-<literal>SELECT</>. An individual column's updated value can be - specified as <literal>DEFAULT</> in the row-constructor case, but not - inside a sub-<literal>SELECT</>. + target column names can be any row-valued expression yielding the correct + number of columns. <productname>PostgreSQL</productname> only allows the + source value to be a <link linkend="sql-syntax-row-constructors">row + constructor</link> or a sub-<literal>SELECT</>. An individual column's + updated value can be specified as <literal>DEFAULT</> in the + row-constructor case, but not inside a sub-<literal>SELECT</>. </para> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml index 2e10ef86dd..37e70ebd69 100644 --- a/doc/src/sgml/ref/vacuum.sgml +++ b/doc/src/sgml/ref/vacuum.sgml @@ -158,7 +158,9 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER"> <listitem> <para> The name (optionally schema-qualified) of a specific table to - vacuum. Defaults to all tables in the current database. + vacuum. If omitted, all regular tables and materialized views in the + current database are vacuumed. If the specified table is a partitioned + table, all of its leaf partitions are vacuumed. </para> </listitem> </varlistentry> @@ -249,39 +251,11 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER"> <title>Examples</title> <para> - The following is an example from running <command>VACUUM</command> on a - table in the regression database: + To clean a single table <literal>onek</literal>, analyze it for + the optimizer and print a detailed vacuum activity report: <programlisting> -regression=# VACUUM (VERBOSE, ANALYZE) onek; -INFO: vacuuming "public.onek" -INFO: index "onek_unique1" now contains 1000 tuples in 14 pages -DETAIL: 3000 index tuples were removed. -0 index pages have been deleted, 0 are currently reusable. -CPU 0.01s/0.08u sec elapsed 0.18 sec. -INFO: index "onek_unique2" now contains 1000 tuples in 16 pages -DETAIL: 3000 index tuples were removed. -0 index pages have been deleted, 0 are currently reusable. -CPU 0.00s/0.07u sec elapsed 0.23 sec. -INFO: index "onek_hundred" now contains 1000 tuples in 13 pages -DETAIL: 3000 index tuples were removed. -0 index pages have been deleted, 0 are currently reusable. -CPU 0.01s/0.08u sec elapsed 0.17 sec. -INFO: index "onek_stringu1" now contains 1000 tuples in 48 pages -DETAIL: 3000 index tuples were removed. -0 index pages have been deleted, 0 are currently reusable. -CPU 0.01s/0.09u sec elapsed 0.59 sec. -INFO: "onek": removed 3000 tuples in 108 pages -DETAIL: CPU 0.01s/0.06u sec elapsed 0.07 sec. -INFO: "onek": found 3000 removable, 1000 nonremovable tuples in 143 pages -DETAIL: 0 dead tuples cannot be removed yet. -There were 0 unused item pointers. -Skipped 0 pages due to buffer pins. -0 pages are entirely empty. -CPU 0.07s/0.39u sec elapsed 1.56 sec. -INFO: analyzing "public.onek" -INFO: "onek": 36 pages, 1000 rows sampled, 1000 estimated total rows -VACUUM +VACUUM (VERBOSE, ANALYZE) onek; </programlisting></para> </refsect1> diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml index 6aef4960ea..10e4d101d2 100644 --- a/doc/src/sgml/ref/vacuumdb.sgml +++ b/doc/src/sgml/ref/vacuumdb.sgml @@ -435,7 +435,7 @@ PostgreSQL documentation <literal>xyzzy</literal>, and analyze a single column <literal>bar</literal> of the table for the optimizer: <screen> -<prompt>$ </prompt><userinput>vacuumdb --analyze --verbose --table 'foo(bar)' xyzzy</userinput> +<prompt>$ </prompt><userinput>vacuumdb --analyze --verbose --table='foo(bar)' xyzzy</userinput> </screen></para> </refsect1> diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml index adfd95aea0..2d1c43ed11 100644 --- a/doc/src/sgml/reference.sgml +++ b/doc/src/sgml/reference.sgml @@ -55,11 +55,14 @@ &alterOperatorClass; &alterOperatorFamily; &alterPolicy; + &alterPublication; &alterRole; &alterRule; &alterSchema; &alterSequence; &alterServer; + &alterStatistics; + &alterSubscription; &alterSystem; &alterTable; &alterTableSpace; @@ -105,11 +108,14 @@ &createOperatorClass; &createOperatorFamily; &createPolicy; + &createPublication; &createRole; &createRule; &createSchema; &createSequence; &createServer; + &createStatistics; + &createSubscription; &createTable; &createTableAs; &createTableSpace; @@ -151,11 +157,14 @@ &dropOperatorFamily; &dropOwned; &dropPolicy; + &dropPublication; &dropRole; &dropRule; &dropSchema; &dropSequence; &dropServer; + &dropStatistics; + &dropSubscription; &dropTable; &dropTableSpace; &dropTSConfig; @@ -237,10 +246,8 @@ &clusterdb; &createdb; - &createlang; &createuser; &dropdb; - &droplang; &dropuser; &ecpgRef; &pgBasebackup; @@ -249,7 +256,7 @@ &pgDump; &pgDumpall; &pgIsready; - &pgReceivexlog; + &pgReceivewal; &pgRecvlogical; &pgRestore; &psqlRef; @@ -279,12 +286,12 @@ &pgarchivecleanup; &pgControldata; &pgCtl; - &pgResetxlog; + &pgResetwal; &pgRewind; &pgtestfsync; &pgtesttiming; &pgupgrade; - &pgxlogdump; + &pgwaldump; &postgres; &postmaster; diff --git a/doc/src/sgml/regress.sgml b/doc/src/sgml/regress.sgml index 7d6bbf3ddc..c89f96a01a 100644 --- a/doc/src/sgml/regress.sgml +++ b/doc/src/sgml/regress.sgml @@ -212,6 +212,12 @@ make installcheck-world <literal>ecpg1_regression</>, or <literal>ecpg2_regression</>, as well as <literal>regression</>. </para> + + <para> + The TAP tests are only run when PostgreSQL was configured with the + option <option>--enable-tap-tests</option>. This is recommended for + development, but can be omitted if there is no suitable Perl installation. + </para> </sect2> <sect2> @@ -271,10 +277,12 @@ make check EXTRA_TESTS=numeric_big </screen> To run the collation tests: <screen> -make check EXTRA_TESTS=collate.linux.utf8 LANG=en_US.utf8 +make check EXTRA_TESTS='collate.icu.utf8 collate.linux.utf8' LANG=en_US.utf8 </screen> The <literal>collate.linux.utf8</> test works only on Linux/glibc - platforms, and only when run in a database that uses UTF-8 encoding. + platforms. The <literal>collate.icu.utf8</literal> test only works when + support for ICU was built. Both tests will only succeed when run in a + database that uses UTF-8 encoding. </para> </sect2> diff --git a/doc/src/sgml/release-10.sgml b/doc/src/sgml/release-10.sgml new file mode 100644 index 0000000000..3ccac676ad --- /dev/null +++ b/doc/src/sgml/release-10.sgml @@ -0,0 +1,2897 @@ +<!-- doc/src/sgml/release-10.sgml --> +<!-- See header comment in release.sgml about typical markup --> + + <sect1 id="release-10"> + <title>Release 10</title> + + <formalpara> + <title>Release date:</title> + <para>2017-09-XX (CURRENT AS OF 2017-05-14)</para> + </formalpara> + + <sect2> + <title>Overview</title> + + <para> + Major enhancements in <productname>PostgreSQL</> 10 include: + </para> + + <!-- Items in this list summarize one or more items below --> + + <itemizedlist> + + <listitem><para> </para></listitem> + </itemizedlist> + + <para> + The above items are explained in more detail in the sections below. + </para> + + </sect2> + + <sect2> + + <title>Migration to Version 10</title> + + <para> + A dump/restore using <xref linkend="app-pg-dumpall">, or use of <xref + linkend="pgupgrade">, is required for those wishing to migrate data + from any previous release. + </para> + + <para> + Version 10 contains a number of changes that may affect compatibility + with previous releases. Observe the following incompatibilities: + </para> + + <itemizedlist> + + <listitem> +<!-- +2017-04-03 [ea69a0dea] Expand hash indexes more gradually. +--> + <para> + <application>pg_upgrade</>-ed hash indexes from previous major + Postgres versions must be rebuilt. + </para> + + <para> + Major hash storage improvements necessitated this requirement. + </para> + </listitem> + + <listitem> +<!-- +2017-03-27 [3371e4d9b] Change default of log_directory to 'log' +--> + <para> + Change the default <link linkend="guc-log-destination">log + directory</> from <filename>pg_log</> to <filename>log</> (Andreas + Karlsson) + </para> + </listitem> + + <listitem> +<!-- +2016-10-20 [f82ec32ac] Rename "pg_xlog" directory to "pg_wal" +--> + <para> + Rename <filename>pg_xlog</> to <link + linkend="wal"><filename>pg_wal</></> (Michael Paquier) + </para> + + <para> + This prevents the write-ahead log directory from being confused as + containing server activity logs, and erroneously truncated. + </para> + </listitem> + + <listitem> +<!-- +2017-02-09 [806091c96] Remove all references to "xlog" from SQL-callable functi +2017-02-09 [85c11324c] Rename user-facing tools with "xlog" in the name to say +2017-02-09 [62e8b3875] Rename command line options for ongoing xlog -> wal conv +2017-02-15 [0dfa89ba2] Replace reference to "xlog-method" with "wal-method" in +--> + <para> + Rename <acronym>SQL</> functions, tools, and options that reference + <quote>xlog</> to <quote>wal</> (Robert Haas) + </para> + + <para> + For example, <function>pg_switch_xlog()</> becomes + <function>pg_switch_wal()</>, <application>pg_receivexlog</> + becomes <application>pg_receivewal</>, and <option>--xlogdir</> + becomes <option>--waldir</>. This might require adjustments for + prior-version scripts. + </para> + </listitem> + + <listitem> +<!-- +2017-03-17 [88e66d193] Rename "pg_clog" directory to "pg_xact". +--> + <para> + Rename transaction status directory <filename>pg_clog</> directory + to <filename>pg_xact</> (Michael Paquier) + </para> + </listitem> + + <listitem> +<!-- +2017-05-11 [d10c626de] Rename WAL-related functions and views to use "lsn" not +--> + <para> + Rename <acronym>WAL</>-related functions and views to use <literal>lsn</> + instead of <literal>location</> (David Rowley) + </para> + </listitem> + + <listitem> +<!-- +2017-01-18 [69f4b9c85] Move targetlist SRF handling from expression evaluation +2017-01-18 [f13a1277a] Doc: improve documentation of new SRF-in-tlist behavior. +--> + <para> + Allow <literal>COALESCE</> and <literal>CASE</> to return multiple + rows when evaluating set-returning functions (Andres Freund). + </para> + + <para> + This also prevents conditionals like <literal>CASE</> from + controlling the execution of set-returning functions because + set-returning functions are now executed earlier. + </para> + </listitem> + + <listitem> +<!-- +2017-01-04 [9a4d51077] Make wal streaming the default mode for pg_basebackup +--> + <para> + Have <application><xref linkend="app-pgbasebackup"></> stream the + <acronym>WAL</> needed to restore the backup by default (Magnus + Hagander) + </para> + + <para> + This changes the <application>pg_basebackup</> + <option>-X</>/<option>--xlog-method</> default to <literal>stream</>. + An option value <literal>none</> has been added to recreate the old + behavior. The <application>pg_basebackup</> option <option>-x</> + has been removed (use <option>-X</> fetch). + </para> + </listitem> + + <listitem> +<!-- +2017-01-14 [05cd12ed5] pg_ctl: Change default to wait for all actions +--> + <para> + Make all <application><xref linkend="app-pg-ctl"></> actions wait + by default for completion (Peter Eisentraut) + </para> + + <para> + Previously some <application>pg_ctl</> actions didn't wait for + completion, and required the use of <option>-w</> to do so. + </para> + </listitem> + + <listitem> +<!-- +2017-05-08 [eb61136dc] Remove support for password_encryption='off' / 'plain'. +--> + <para> + Remove the ability to store unencrypted passwords on the server + (Heikki Linnakangas) + </para> + + <para> + The server-side variable <xref linkend="guc-password-encryption"> + no longer supports <literal>off</> or <literal>plain</>. + The <literal>UNENCRYPTED</> option is no longer supported for + <command>CREATE/ALTER USER ... PASSSWORD</>. Similarly, the + <option>--unencrypted</> has been removed from <command>createuser</>. + The default for <option>password_encryption</> is still + <literal>md5</>, and users migrating passwords from older systems + will have them stored encrypted by default in this release. + </para> + </listitem> + + <listitem> +<!-- +2016-10-26 [94aceed31] Support multi-dimensional arrays in PL/python. +2016-10-26 [cfd9c87a5] Only treat Python Lists as array dimensions. +--> + <para> + Allow multi-dimensional arrays to be passed into PL/Python functions, + and returned as nested Python lists (Alexey Grishchenko, Dave Cramer, + Heikki Linnakangas) + </para> + + <para> + This makes a backwards-incompatible change to the handling of + composite types in arrays. Previously, you could return an array of + composite types as "[[col1, col2], [col1, col2]]", but now that is + interpreted as a two- dimensional array. Composite types in arrays + must now be returned as Python tuples, not lists, to resolve the + ambiguity. I.e. "[(col1, col2), (col1, col2)]". See the documentation + for more details. CLARIFY + </para> + </listitem> + + <listitem> +<!-- +2017-02-27 [817f2a586] Remove PL/Tcl's "module" facility. +--> + <para> + Remove PL/Tcl's "module" auto-loading facility (Tom Lane) + </para> + + <para> + Replaced by new PL/Tcl startup <acronym>GUC</>s. + </para> + </listitem> + + <listitem> +<!-- +2016-12-23 [e13486eba] Remove sql_inheritance GUC. +--> + <para> + Remove <varname>sql_inheritance</> <acronym>GUC</> (Robert Haas) + </para> + + <para> + Changing this from the default value caused queries referencing + parent tables to not include children tables. The <acronym>SQL</> + standard requires such behavior and this has been the default since + Postgres 7.1. + </para> + </listitem> + + <listitem> +<!-- +2017-02-15 [51ee6f316] Replace min_parallel_relation_size with two new GUCs. +--> + <para> + Add <acronym>GUC</>s <xref linkend="guc-min-parallel-table-scan-size"> + and <xref linkend="guc-min-parallel-index-scan-size"> to control + parallel operation (Amit Kapila, Robert Haas) + </para> + + <para> + This replaces <varname>min_parallel_relation_size</>, which was + too generic. + </para> + </listitem> + + <listitem> +<!-- +2016-10-12 [64f3524e2] Remove pg_dump/pg_dumpall support for dumping from pre-8 +--> + <para> + Remove <application>pg_dump</>/<application>pg_dumpall</> support + for dumping from pre-8.0 servers (Tom Lane) + </para> + + <para> + Users needing dump support for pre-8.0 servers need to use dump + binaries from Postgres 9.6. + </para> + </listitem> + + <listitem> +<!-- +2017-02-23 [b6aa17e0a] De-support floating-point timestamps. +--> + <para> + Remove support for floating-point datetimes/timestamps (Tom Lane) + </para> + + <para> + This removes configure's <option>--disable-integer-datetimes</> + option. Floating-point datetimes/timestamps have not been the + default since Postgres 8.3 and have few advantages. + </para> + </listitem> + + <listitem> +<!-- +2016-10-11 [2f1eaf87e] Drop server support for FE/BE protocol version 1.0. +--> + <para> + Remove support for client/server protocol version 1.0 (Tom Lane) + </para> + + <para> + This protocol hasn't had client support since Postgres 6.3. + </para> + </listitem> + + <listitem> +<!-- +2017-02-13 [7ada2d31f] Remove contrib/tsearch2. +--> + <para> + Remove contrib/tsearch2 (Robert Haas) + </para> + + <para> + This removes compatibility with the contrib version of full text + search that shipped in pre-8.3 Postgres versions. + </para> + </listitem> + + <listitem> +<!-- +2017-03-23 [50c956add] Remove createlang and droplang +--> + <para> + Remove createlang and droplang command-line applications (Peter + Eisentraut) + </para> + </listitem> + + <listitem> +<!-- +2017-03-30 [5ded4bd21] Remove support for version-0 calling conventions. +--> + <para> + Remove support for version-0 function calling conventions (Andres + Freund) + </para> + </listitem> + + <listitem> +<!-- +2016-10-11 [2b860f52e] Remove "sco" and "unixware" ports. +--> + <para> + Remove <systemitem class="osname">SCO</> and <systemitem + class="osname">Unixware</> ports (Tom Lane) + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2> + <title>Changes</title> + + <para> + Below you will find a detailed account of the changes between + <productname>PostgreSQL</productname> 10 and the previous major + release. + </para> + + <sect3> + <title>Server</title> + + <sect4> + <title>Parallel Queries</title> + + <itemizedlist> + + <listitem> +<!-- +2017-02-15 [569174f1b] btree: Support parallel index scans. +2017-02-15 [5262f7a4f] Add optimizer and executor support for parallel index sc +2017-02-19 [0414b26ba] Add optimizer and executor support for parallel index-on +--> + <para> + Support parallel btree index scans (Rahila Syed, Amit Kapila, + Robert Haas, Rafia Sabih) + </para> + + <para> + Allows btree index pages to be checked by separate parallel + workers. + </para> + </listitem> + + <listitem> +<!-- +2017-03-08 [98e6e8904] tidbitmap: Support shared iteration. +2017-03-08 [f35742ccb] Support parallel bitmap heap scans. +--> + <para> + Support parallel bitmap heap scans (Dilip Kumar) + </para> + + <para> + This allows a single index scan to dispatch parallel workers to + process different areas of the heap. + </para> + </listitem> + + <listitem> +<!-- +2017-03-07 [3bc7dafa9] Consider parallel merge joins. +--> + <para> + Allow merge joins to be performed in parallel (Dilip Kumar) + </para> + </listitem> + + <listitem> +<!-- +2017-02-14 [5e6d8d2bb] Allow parallel workers to execute subplans. +--> + <para> + Allow non-correlated subqueries to be run in parallel (Amit Kapila) + </para> + </listitem> + + <listitem> +<!-- +2017-03-09 [355d3993c] Add a Gather Merge executor node. +--> + <para> + Improve ability of parallel workers to return pre-sorted data + (Rushabh Lathia) + </para> + </listitem> + + <listitem> +<!-- +2017-03-24 [61c2e1a95] Improve access to parallel query from procedural languag +--> + <para> + Increase parallel query usage in procedural language functions + (Robert Haas, Rafia Sabih) + </para> + </listitem> + + <listitem> +<!-- +2016-12-02 [b460f5d66] Add max_parallel_workers GUC. +2016-12-05 [2b959d495] Reduce the default for max_worker_processes back to 8. +--> + <para> + Add <acronym>GUC</> <xref linkend="guc-max-parallel-workers"> + to limit the number of worker processes that can be used for + query parallelism (Julien Rouhaud) + </para> + + <para> + This can be set lower than <xref + linkend="guc-max-worker-processes"> to reserve worker processes + for purposes other than parallel queries. + </para> + </listitem> + + </itemizedlist> + + </sect4> + + <sect4> + <title>Indexes</title> + + <itemizedlist> + + <listitem> +<!-- +2016-08-23 [77e290682] Create an SP-GiST opclass for inet/cidr. +--> + <para> + Add <acronym>SP-GiST</> index support for <type>INET</> and + <type>CIDR</> data types (Emre Hasegeli) + </para> + + <para> + These data types already had GiST support. + </para> + </listitem> + + <listitem> +<!-- +2017-03-23 [218f51584] Reduce page locking in GIN vacuum +--> + <para> + Reduce page locking during vacuuming of <acronym>GIN</> indexes + (Andrey Borodin) + </para> + </listitem> + + <listitem> +<!-- +2017-04-01 [7526e1022] BRIN auto-summarization +--> + <para> + Add option to allow <acronym>BRIN</> index summarization to happen + more aggressively (Álvaro Herrera) + </para> + + <para> + Specifically, a new <link linkend="SQL-ALTERINDEX"><command>CREATE + INDEX</></> option allows auto-summarizion of the + previous <acronym>BRIN</> page range when a new page + range is created. + </para> + </listitem> + + <listitem> +<!-- +2017-04-01 [c655899ba] BRIN de-summarization +--> + <para> + Add functions to remove and re-add <acronym>BRIN</> + summarization for <acronym>BRIN</> index ranges (Álvaro + Herrera) + </para> + + <para> + New <acronym>SQL</> function <link + linkend="functions-admin-index-table"><function>brin_summarize_range()</></> + updates <acronym>BRIN</> index summarization for a specified + range and <function>brin_desummarize_range()</> removes it. + This is helpful to update summarization of a range that is now + smaller due to <command>UPDATE</>s and <command>DELETE</>s. + </para> + </listitem> + + <listitem> +<!-- +2017-04-06 [7e534adcd] Fix BRIN cost estimation +--> + <para> + Improve accuracy in determining if a <acronym>BRIN</> index scan + is beneficial (David Rowley, Emre Hasegeli) + </para> + </listitem> + + <listitem> +<!-- +2016-09-09 [b1328d78f] Invent PageIndexTupleOverwrite, and teach BRIN and GiST +--> + <para> + Allow faster <acronym>GiST</> inserts and updates by reusing + index space more efficiently (Andrey Borodin) + </para> + </listitem> + + </itemizedlist> + + <sect5> + <title><link linkend="indexes-types">Hash Indexes</link></title> + + <itemizedlist> + + <listitem> +<!-- +2017-02-27 [30df93f69] hash: Refactor overflow page allocation. +2017-03-14 [c11453ce0] hash: Add write-ahead logging support. +2017-02-27 [b0f18cb77] hash: Refactor bucket squeeze code. +--> + <para> + Add write-ahead logging support to hash indexes (Amit Kapila) + </para> + + <para> + This makes hash indexes crash-safe and replicated, and removes + the warning message about their use. + </para> + </listitem> + + <listitem> +<!-- +2016-11-30 [6d46f4783] Improve hash index bucket split behavior. +2017-02-07 [293e24e50] Cache hash index's metapage in rel->rd_amcache. +--> + <para> + Improve hash bucket split performance by reducing locking + requirements (Amit Kapila, Mithun Cy) + </para> + + <para> + Also cache hash index meta-information for faster lookups. + </para> + </listitem> + + <listitem> +<!-- +2017-04-03 [ea69a0dea] Expand hash indexes more gradually. +--> + <para> + Improve efficiency of hash index growth (Amit Kapila, Mithun Cy) + </para> + </listitem> + + <listitem> +<!-- +2017-03-15 [6977b8b7f] Port single-page btree vacuum logic to hash indexes. +--> + <para> + Allow single-page hash pruning (Ashutosh Sharma) + </para> + </listitem> + + </itemizedlist> + + </sect5> + + </sect4> + + <sect4> + + <title>Locking</title> + + <itemizedlist> + + <listitem> +<!-- +2017-03-31 [64d4da511] For foreign keys, check REFERENCES privilege only on the +--> + <para> + Only check for <literal>REFERENCES</> permission on referenced + tables (Tom Lane) + </para> + + <para> + Previously <literal>REFERENCES</> permission on the referencing + table was also required. + </para> + </listitem> + + <listitem> +<!-- +2016-09-05 [15bc038f9] Relax transactional restrictions on ALTER TYPE ... ADD V +--> + <para> + Reduce locking required for adding values to enum types (Andrew + Dunstan, Tom Lane) + </para> + + <para> + Previously it was impossible to run <command>ALTER TYPE ... ADD + VALUE</> in a transaction block unless the enum type was created + in the same block. Now, only references to uncommitted enum + values from other transactions is prohibited. + </para> + </listitem> + + <listitem> +<!-- +2017-04-07 [c63172d60] Add GUCs for predicate lock promotion thresholds. +--> + <para> + Allow tuning of predicate lock promotion thresholds (Dagfinn + Ilmari Mannsåker) + </para> + + <para> + The new settings are <xref + linkend="guc-max-pred-locks-per-relation"> and + <xref linkend="guc-max-pred-locks-per-page">. + </para> + </listitem> + + </itemizedlist> + + </sect4> + + <sect4> + <title>Optimizer</title> + + <itemizedlist> + + <listitem> +<!-- +2017-03-24 [7b504eb28] Implement multivariate n-distinct coefficients +2017-04-05 [2686ee1b7] Collect and use multi-column dependency stats +--> + <para> + Add multi-column optimizer statistics to compute the correlation + ratio and number of distinct values (Tomas Vondra, David Rowley, + Álvaro Herrera) + </para> + + <para> + New commands are <command><link + linkend="SQL-CREATESTATISTICS">CREATE</></>, + <command><link linkend="SQL-ALTERSTATISTICS">ALTER</></>, and + <command><link linkend="SQL-DROPSTATISTICS">DROP STATISTICS</></>. + This is helpful in + estimating query memory usage and when combining the statistics + from individual columns. + </para> + </listitem> + + <listitem> +<!-- +2017-01-15 [0777f7a2e] Fix matching of boolean index columns to sort ordering. +--> + <para> + Improve planner matching of boolean indexes (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +2017-01-18 [215b43cdc] Improve RLS planning by marking individual quals with se +--> + <para> + Improve performance of queries referencing row-level security + restrictions (Tom Lane) + </para> + + <para> + The optimizer now has more flexibility in reordering executor + behavior. + </para> + </listitem> + + </itemizedlist> + + </sect4> + + <sect4> + <title>General Performance</title> + + <itemizedlist> + + <listitem> +<!-- +2016-09-02 [9cca11c91] Speed up SUM calculation in numeric aggregates. +--> + <para> + Speed up <function>SUM()</> calculations (Heikki Linnakangas) + </para> + + <para> + This uses an optimized numeric accumulator. + </para> + </listitem> + + <listitem> +<!-- +2017-03-13 [aeed17d00] Use radix tree for character encoding conversions. +--> + <para> + Improve the performance of character encoding conversions by + using radix trees (Kyotaro Horiguchi, Heikki Linnakangas) + </para> + </listitem> + + <listitem> +<!-- +2017-03-25 [b8d7f053c] Faster expression evaluation and targetlist projection. +--> + <para> + Reduce the function call overhead during query execution (Andres + Freund) + </para> + + <para> + This is particularly helpful for queries that process many rows. + </para> + </listitem> + + <listitem> +<!-- +2017-03-27 [b5635948a] Support hashed aggregation with grouping sets. +--> + <para> + Improve the performance of grouping sets (Andrew Gierth) + </para> + </listitem> + + <listitem> +<!-- +2017-04-07 [9c7f5229a] Optimize joins when the inner relation can be proven uni +--> + <para> + Use uniqueness guarantees to optimize certain join types (David + Rowley) + </para> + </listitem> + + <listitem> +<!-- +2017-03-29 [f90d23d0c] Implement SortSupport for macaddr data type +--> + <para> + Improve sort performance of the macaddr data type (Brandur Leach) + </para> + </listitem> + + <listitem> +<!-- +2017-03-27 [090010f2e] Improve performance of find_tabstat_entry()/get_tabstat_ +--> + <para> + Reduce statistics tracking overhead in sessions that reference + many thousands of relations (Aleksander Alekseev) + </para> + </listitem> + + </itemizedlist> + + </sect4> + + <sect4> + <title>Monitoring</title> + + <itemizedlist> + + <listitem> +<!-- +2016-12-20 [1753b1b02] Add pg_sequence system catalog +2016-11-18 [67dc4ccbb] Add pg_sequences view +--> + <para> + Create a <link + linkend="catalog-pg-sequence"><structname>pg_sequence</></> + system catalog to store sequence metadata (Peter Eisentraut) + </para> + + <para> + Sequence metadata includes start, increment, etc, + which is now transactional. Sequence counters are + still stored in separate heap relations. Also add <link + linkend="view-pg-sequences"><structname>pg_sequences</></> view + to show all sequences. + </para> + </listitem> + + <listitem> +<!-- +2017-03-08 [f9b1a0dd4] Expose explain's SUMMARY option +--> + <para> + Allow explicit control over <command><link + linkend="SQL-EXPLAIN">EXPLAIN</></>'s display of planning and + execution time (Ashutosh Bapat) + </para> + + <para> + By default planning and execution time are displayed by + <command>EXPLAIN ANALYZE</> and are not displayed in other cases. + The new <command>EXPLAIN</> option <literal>SUMMARY</> allows + explicit control of this. + </para> + </listitem> + + <listitem> +<!-- +2017-03-18 [17f8ffa1e] Fix REFRESH MATERIALIZED VIEW to report activity to the +--> + <para> + Properly update the statistics collector during <link + linkend="SQL-REFRESHMATERIALIZEDVIEW"><command>REFRESH MATERIALIZED + VIEW</></> (Jim Mlodgenski) + </para> + </listitem> + + <listitem> +<!-- +2017-03-30 [25fff4079] Default monitoring roles +--> + <para> + Add default monitoring roles (Dave Page) + </para> + + <para> + New roles <literal>pg_monitor</>, <literal>pg_read_all_settings</>, + <literal>pg_read_all_stats</>, and <literal>pg_stat_scan_tables</> + allow simplified permission configuration. + </para> + </listitem> + + </itemizedlist> + + <sect5> + <title>Logging</title> + + <itemizedlist> + + <listitem> +<!-- +2016-10-17 [7d3235ba4] By default, set log_line_prefix = '%m [%p] '. +--> + <para> + Change <xref linkend="guc-log-line-prefix"> default to include + current timestamp with milliseconds and the process id (Christoph + Berg) + </para> + + <para> + The previous default was not to output a prefix. + </para> + </listitem> + + <listitem> +<!-- +2017-03-16 [befd73c50] Add pg_ls_logdir() and pg_ls_waldir() functions. +--> + <para> + Add functions to return the log and <acronym>WAL</> directory + names (Dave Page) + </para> + + <para> + The new functions are <link + linkend="functions-admin-genfile-table"><function>pg_ls_logdir()</></> + and + <link + linkend="functions-admin-genfile-table"><function>pg_ls_waldir()</></> + and can be + executed by non-super users with the proper permissions. + </para> + </listitem> + + <listitem> +<!-- +2017-03-03 [19dc233c3] Add pg_current_logfile() function. +--> + <para> + Add function <link + linkend="functions-info-session-table"><function>pg_current_logfile()</></> + to read syslog's current stderr and csvlog output file names + (Gilles Darold) + </para> + </listitem> + + <listitem> +<!-- +2017-03-10 [f9dfa5c97] Improve postmaster's logging of listen socket creation. +2017-03-14 [2b32ac2a5] Include port number when logging successful binding to a +--> + <para> + Report the address and port number of successful startup socket + binding in the server logs (Tom Lane) + </para> + + <para> + Also, report bind socket failure details in the server logs. + </para> + </listitem> + + <listitem> +<!-- +2017-03-10 [6ec4c8584] Reduce log verbosity of startup/shutdown for launcher su +--> + <para> + Reduce log chatter about the starting and stopping of launcher + subprocesses (Tom Lane) + </para> + + <para> + These are now <literal>DEBUG1</>-level messages. + </para> + </listitem> + + <listitem> +<!-- +2016-11-17 [a43f1939d] Remove or reduce verbosity of some debug messages. +--> + <para> + Reduce message verbosity of lower-numbered debug levels + controlled by + <xref linkend="guc-log-min-messages"> (Robert Haas) + </para> + + <para> + This also changes the verbosity of <xref + linkend="guc-client-min-messages"> debug levels. + </para> + </listitem> + + </itemizedlist> + + </sect5> + + <sect5> + <title><link linkend="pg-stat-activity-view"><structname>pg_stat_activity</></link></title> + + <itemizedlist> + + <listitem> +<!-- +2016-10-04 [6f3bd98eb] Extend framework from commit 53be0b1ad to report latch w +--> + <para> + Add <structname>pg_stat_activity</> reporting of latch wait states + (Michael Paquier, Robert Haas) + </para> + + <para> + This includes the remaining wait events, like client reads, + client writes, and synchronous replication. + </para> + </listitem> + + <listitem> +<!-- +2017-03-18 [249cf070e] Create and use wait events for read, write, and fsync op +--> + <para> + Add <structname>pg_stat_activity</> reporting of waits on reads, + writes, and fsyncs (Rushabh Lathia) + </para> + </listitem> + + <listitem> +<!-- +2017-03-26 [fc70a4b0d] Show more processes in pg_stat_activity. +--> + <para> + Show auxiliary processes and background workers in + <structname>pg_stat_activity</> (Kuntal Ghosh) + </para> + + <para> + New column <structfield>backend_type</> identifies the process + type. + </para> + </listitem> + + <listitem> +<!-- +2016-09-12 [fc3d4a44e] Identify walsenders in pg_stat_activity +--> + <para> + Display walsender processes in <structname>pg_stat_activity</> + (Michael Paquier) + </para> + + <para> + This simplifies monitoring. + </para> + </listitem> + + <listitem> +<!-- +2017-02-22 [4c728f382] Pass the source text for a parallel query to the workers +--> + <para> + Allow <structname>pg_stat_activity</> to show the source query + being executed by parallel workers (Rafia Sabih) + </para> + </listitem> + + <listitem> +<!-- +2016-12-16 [3761fe3c2] Simplify LWLock tranche machinery by removing array_base +--> + <para> + Rename + <structname>pg_stat_activity</>.<structfield>wait_event_type</> + values <literal>LWLockTranche</> and + <literal>LWLockNamed</> to <literal>LWLock</> (Robert Haas) + </para> + + <para> + This makes the output more consistent. + </para> + </listitem> + + </itemizedlist> + + </sect5> + </sect4> + + <sect4> + <title><acronym>Authentication</></title> + + <itemizedlist> + + <listitem> +<!-- +2017-03-07 [818fd4a67] Support SCRAM-SHA-256 authentication (RFC 5802 and 7677) +2017-03-24 [7ac955b34] Allow SCRAM authentication, when pg_hba.conf says 'md5'. +2017-04-07 [60f11b87a] Use SASLprep to normalize passwords for SCRAM authentica +2017-04-18 [c727f120f] Rename "scram" to "scram-sha-256" in pg_hba.conf and pas +--> + <para> + Add <link linkend="auth-pg-hba-conf"><literal>SCRAM-SHA-256</></> + support for password negotiation and storage (Michael Paquier, + Heikki Linnakangas) + </para> + + <para> + This provides better security than the existing <literal>md5</> + negotiation and storage method. + </para> + </listitem> + + <listitem> +<!-- +2016-09-28 [babe05bc2] Turn password_encryption GUC into an enum. +--> + <para> + Change <acronym>GUC</> <xref linkend="guc-password-encryption"> + from <type>boolean</> to <type>enum</> (Michael Paquier) + </para> + + <para> + This was necessary to support additional password hashing options. + </para> + </listitem> + + <listitem> +<!-- +2017-01-30 [de16ab723] Invent pg_hba_file_rules view to show the content of pg_ +--> + <para> + Add view <link + linkend="view-pg-hba-file-rules"><structname>pg_hba_file_rules</></> + to display the contents of <filename>pg_hba.conf</> (Haribabu + Kommi) + </para> + + <para> + This shows the file contents, not the currently active settings. + </para> + </listitem> + + <listitem> +<!-- +2017-03-22 [6b76f1bb5] Support multiple RADIUS servers +--> + <para> + Support multiple <acronym>RADIUS</> servers (Magnus Hagander) + </para> + + <para> + All the <acronym>RADIUS</> related parameters are now plural and + support a comma-separated list of servers. + </para> + </listitem> + + </itemizedlist> + + </sect4> + + <sect4> + <title>Server Configuration</title> + + <itemizedlist> + + <listitem> +<!-- +2017-01-02 [de41869b6] Allow SSL configuration to be updated at SIGHUP. +2017-01-03 [1e942c747] Disable prompting for passphrase while (re)loading SSL c +2017-01-04 [6667d9a6d] Re-allow SSL passphrase prompt at server start, but not +--> + <para> + Allow <acronym>SSL</> configuration to be updated during + configuration reload (Andreas Karlsson, Tom Lane) + </para> + + <para> + This allows <acronym>SSL</> to be reconfigured without a server + restart by using <command>pg_ctl reload</>, <command>SELECT + pg_reload_conf()</>, or sending a <literal>SIGHUP</> signal. + Reload <acronym>SSL</> configuration updates do not work if the + <acronym>SSL</> key requires a passphrase. + </para> + </listitem> + + <listitem> +<!-- +2016-11-30 [81c52728f] doc: Remove claim about large shared_buffers on Windows +--> + <para> + Remove documented restriction about using large shared buffers on + <systemitem class="osname">Windows</> (Takayuki Tsunakawa) + </para> + </listitem> + + <listitem> +<!-- +2017-03-06 [21d4e2e20] Reduce lock levels for table storage params related to p +2017-04-05 [68ea2b7f9] Reduce lock level for CREATE STATISTICS +--> + <para> + Reduce locking required to change table params (Simon Riggs, + Fabrízio Mello) + </para> + + <para> + For example, changing a table's <xref + linkend="guc-effective-io-concurrency"> setting can now be done + with a more lightweight lock. + </para> + </listitem> + + <listitem> +<!-- +2017-02-02 [14ca9abfb] Increase upper bound for bgwriter_lru_maxpages. +--> + <para> + Make the maximum value of <xref + linkend="guc-bgwriter-lru-maxpages"> effectively unlimited + (Jim Nasby) + </para> + </listitem> + + </itemizedlist> + + </sect4> + + <sect4> + <title>Reliability</title> + + <itemizedlist> + + <listitem> +<!-- +2017-03-27 [1b02be21f] Fsync directory after creating or unlinking file. +--> + <para> + Perform an fsync on the directory after creating or unlinking files + (Michael Paquier) + </para> + + <para> + This reduces the risk of data loss after a power failure. + </para> + </listitem> + + </itemizedlist> + + <sect5> + <title><link linkend="wal">Write-Ahead Log</> (<acronym>WAL</>)</title> + + <itemizedlist> + + <listitem> +<!-- +2016-12-22 [6ef2eba3f] Skip checkpoints, archiving on idle systems. +--> + <para> + Prevent checkpoints and <acronym>WAL</> archiving on + otherwise-idle systems (Michael Paquier) + </para> + </listitem> + + <listitem> +<!-- +2017-02-08 [a507b8690] Add WAL consistency checking facility. +2017-03-14 [bb4a39637] hash: Support WAL consistency checking. +--> + <para> + Add <acronym>GUC</> <xref linkend="guc-wal-consistency-checking"> + to add details to <acronym>WAL</> that can be sanity-checked on + the standby (Kuntal Ghosh, Robert Haas) + </para> + + <para> + Any sanity-check failure generates a fatal error on the standby. + </para> + </listitem> + + <listitem> +<!-- +2017-04-05 [00b6b6feb] Allow -\-with-wal-segsize=n up to n=1024MB +--> + <para> + Increase the maximum configurable <acronym>WAL</> segment size + to one gigabyte (Beena Emerson) + </para> + + <para> + Larger <acronym>WAL</> segment sizes allows for fewer + <xref linkend="guc-archive-command"> invocations and fewer + <acronym>WAL</> files to manage. + </para> + </listitem> + + </itemizedlist> + + </sect5> + + </sect4> + + </sect3> + + <sect3> + <title>Replication and Recovery</title> + + <itemizedlist> + + <listitem> +<!-- +2017-01-20 [665d1fad9] Logical replication +2017-03-23 [7c4f52409] Logical replication support for initial data copy +2017-04-12 [ff7bce174] Add max_sync_workers_per_subscription to postgresql.conf +--> + <para> + Add the ability to <link linkend="logical-replication">logically + replicate</> tables to standby servers (Petr Jelinek) + </para> + + <para> + This allows more fine-grained replication options, including + replication between different major versions of Postgres and + selective-table replication. + </para> + </listitem> + + <listitem> +<!-- +2016-12-19 [3901fd70c] Support quorum-based synchronous replication. +--> + <para> + Allow waiting for commit acknowledgement from standby + servers irrespective of the order they appear in <xref + linkend="guc-synchronous-standby-names"> (Masahiko Sawada) + </para> + + <para> + Previously the server always waited for the active standbys that + appeared first in <varname>synchronous_standby_names</>. The new + <varname>synchronous_standby_names</> keyword <literal>ANY</> allows + waiting for any number of standbys irrespective of their ordering. + This is known as quorum commit. + </para> + </listitem> + + <listitem> +<!-- +2017-01-14 [f6d6d2920] Change default values for backup and replication paramet +2017-05-02 [34fc61673] Change hot_standby default value to 'on' +--> + <para> + Reduce configuration necessary to perform streaming backup and + replication (Magnus Hagander, Dang Minh Huong) + </para> + + <para> + Specifically, defaults were changed for <xref + linkend="guc-wal-level">, <xref linkend="guc-max-wal-senders">, + <xref linkend="guc-max-replication-slots">, and <xref + linkend="guc-hot-standby">. + </para> + </listitem> + + <listitem> +<!-- +2017-03-09 [be37c2120] Enable replication connections by default in pg_hba.conf +--> + <para> + Enable replication from localhost connections by default in + <link linkend="auth-pg-hba-conf"><filename>pg_hba.conf</></> + (Michael Paquier) + </para> + + <para> + Previously <filename>pg_hba.conf</>'s replication connection + lines were commented out. This is particularly useful for + <application><xref linkend="app-pgbasebackup"></>. + </para> + </listitem> + + <listitem> +<!-- +2017-03-23 [6912acc04] Replication lag tracking for walsenders +--> + <para> + Add columns to <link + linkend="monitoring-stats-views-table"><structname>pg_stat_replication</></> + to report replication delay times (Thomas Munro) + </para> + + <para> + The new columns are <structfield>write_lag</>, + <structfield>flush_lag</>, and <structfield>replay_lag</>. + </para> + </listitem> + + <listitem> +<!-- +2016-09-03 [35250b6ad] New recovery target recovery_target_lsn +--> + <para> + Add specification of a Log Sequence Number (<acronym>LSN</>) + stopping point in + <link linkend="recovery-config"><filename>recovery.conf</></> + (Michael Paquier) + </para> + + <para> + Previously only specification of the stop name, time, timeline, + xid, and immediate were supported. + </para> + </listitem> + + <listitem> +<!-- +2017-03-22 [017e4f258] Expose waitforarchive option through pg_stop_backup() +--> + <para> + Allow users to disable <link + linkend="functions-admin"><function>pg_stop_backup()</></>'s + waiting for all <acronym>WAL</> to be archived (David Steele) + </para> + + <para> + An optional second argument to <function>pg_stop_backup()</> + controls that behavior. + </para> + </listitem> + + <listitem> +<!-- +2016-12-12 [a924c327e] Add support for temporary replication slots +--> + <para> + Allow creation of <link + linkend="functions-replication-table">temporary replication slots</> + (Petr Jelinek) + </para> + + <para> + Temporary slots are automatically removed on session exit or error. + </para> + </listitem> + + <listitem> +<!-- +2017-03-22 [9b013dc23] Improve performance of replay of AccessExclusiveLocks +--> + <para> + Improve performance of hot standby replay with better tracking of + Access Exclusive locks (Simon Riggs, David Rowley) + </para> + </listitem> + + <listitem> +<!-- +2017-04-04 [728bd991c] Speedup 2PC recovery by skipping two phase state files i +--> + <para> + Speed up two-phase commit recovery performance (Stas Kelvich, + Nikhil Sontakke, Michael Paquier) + </para> + </listitem> + + </itemizedlist> + + </sect3> + + <sect3> + <title>Queries</title> + + <itemizedlist> + + <listitem> +<!-- +2017-03-08 [fcec6caaf] Support XMLTABLE query expression +--> + <para> + Add <link + linkend="functions-xml-processing-xmltable"><function>XMLTABLE</></> + function that converts <type>XML</>-formatted data into a row set + (Pavel Stehule, Álvaro Herrera) + </para> + </listitem> + + <listitem> +<!-- +2016-11-22 [906bfcad7] Improve handling of "UPDATE ... SET (column_list) = row_ +--> + <para> + Allow <literal>ROW</> to supply values to <command>UPDATE ... SET + (column_list)</> (Tom Lane) + </para> + + <para> + Also allow row values to be supplied by table.*. + </para> + </listitem> + + <listitem> +<!-- +2016-09-05 [c54159d44] Make locale-dependent regex character classes work for l +--> + <para> + Fix regular expression locale class handling for bytes greater + than <literal>U+7FF</> (Tom Lane) + </para> + + <para> + Previously such classes were not recognized. + </para> + </listitem> + + </itemizedlist> + + </sect3> + + <sect3> + <title>Utility Commands</title> + + <itemizedlist> + + <listitem> +<!-- +2016-12-07 [f0e44751d] Implement table partitioning. +--> + <para> + Add table <link linkend="SQL-CREATETABLE-PARTITION">partitioning + syntax</> that automatically creates partition constraints and + <command>INSERT</> routing (Amit Langote) + </para> + + <para> + The syntax supports range and list partitioning. + </para> + </listitem> + + <listitem> +<!-- +2016-11-04 [8c48375e5] Implement syntax for transition tables in AFTER triggers +2017-04-04 [5ebeb579b] Follow-on cleanup for the transition table patch. +2017-03-31 [597027163] Add transition table support to plpgsql. +--> + <para> + Add <link linkend="SQL-CREATETRIGGER"><literal>AFTER</> trigger</> + transition table to record changed rows (Kevin Grittner) + </para> + + <para> + Transition table contents are accessible from server-side languages. + </para> + </listitem> + + <listitem> +<!-- +2016-12-05 [093129c9d] Add support for restrictive RLS policies +--> + <para> + Allow <link linkend="SQL-CREATEPOLICY">restrictive row-level + security policies</> (Stephen Frost) + </para> + + <para> + Previously all security policies were permissive, meaning that any + matching policy allowed access. Optional restrictive policies must + match for access to be granted. These policy types can be combined. + </para> + </listitem> + + <listitem> +<!-- +2017-03-28 [ab89e465c] Altering default privileges on schemas +--> + <para> + Allow <link linkend="SQL-ALTERDEFAULTPRIVILEGES">default + permissions</> on schemas (Matheus Oliveira) + </para> + + <para> + This is done using the <literal>ALTER DEFAULT PRIVILEGES</> command. + </para> + </listitem> + + <listitem> +<!-- +2017-02-10 [2ea5b06c7] Add CREATE SEQUENCE AS <data type> clause +--> + <para> + Add <link linkend="SQL-CREATESEQUENCE"><command>CREATE SEQUENCE + AS</></> command to create a sequence matching an integer data type + (Peter Eisentraut) + </para> + + <para> + This simplifies the creation of sequences matching the range of + base columns. + </para> + </listitem> + + <listitem> +<!-- +2016-11-10 [279c439c7] Support "COPY view FROM" for views with INSTEAD OF INSER +--> + <para> + Allow <command>COPY view FROM</> on views with <literal>INSTEAD + INSERT</> triggers (Haribabu Kommi) + </para> + + <para> + The triggers are fed the rows from <command>COPY</>. + </para> + </listitem> + + <listitem> +<!-- +2017-03-14 [aefeb6874] Allow referring to functions without arguments when uniq +--> + <para> + Allow the specification of a function name without arguments in + <acronym>DDL</> commands, when unique (Peter Eisentraut) + </para> + + <para> + For example, allow <link linkend="SQL-DROPFUNCTION"><command>DROP + FUNCTION</></> on a function name without arguments if there + is only one function with that name. This is required by the + <acronym>SQL</> standard. + </para> + </listitem> + + <listitem> +<!-- +2017-03-06 [583f6c414] Allow dropping multiple functions at once +--> + <para> + Allow multiple functions, operators, and aggregates to be dropped + with a single <command>DROP</> command (Peter Eisentraut) + </para> + </listitem> + + <listitem> +<!-- +2017-03-20 [b6fb534f1] Add IF NOT EXISTS for CREATE SERVER and CREATE USER MAPP +--> + <para> + Add <literal>IF NOT EXISTS</> for <link + linkend="SQL-CREATESERVER"><command>CREATE SERVER</></> and + <link linkend="SQL-CREATEUSERMAPPING"><command>CREATE USER + MAPPING</></> (Anastasia + Lubennikova) + </para> + </listitem> + + <listitem> +<!-- +2017-02-15 [6d16ecc64] Add CREATE COLLATION IF NOT EXISTS clause +--> + <para> + Add <literal>IF NOT EXISTS</> clause to <link + linkend="SQL-CREATECOLLATION"><command>CREATE COLLATION</></> + (Peter Eisentraut) + </para> + </listitem> + + <listitem> +<!-- +2017-03-25 [70adf2fbe] Make VACUUM VERBOSE report the number of skipped frozen +2017-03-03 [9eb344faf] Allow vacuums to report oldestxmin +--> + <para> + Have <link linkend="SQL-VACUUM"><command>VACUUM VERBOSE</></> report + the number of skipped frozen pages and oldest xmin (Masahiko + Sawada, Simon Riggs) + </para> + + <para> + This information is also included in <xref + linkend="guc-log-autovacuum-min-duration"> output. + </para> + </listitem> + + <listitem> +<!-- +2017-01-23 [7e26e02ee] Prefetch blocks during lazy vacuum's truncation scan +--> + <para> + Improve speed of <command>VACUUM</>'s removal of trailing empty + heap pages (Claudio Freire, Álvaro Herrera) + </para> + + <para> + This information is also included in <xref + linkend="guc-log-autovacuum-min-duration"> output. + </para> + </listitem> + + <listitem> +<!-- +2017-01-16 [d43a619c6] Fix check_srf_call_placement() to handle VALUES cases co +--> + <para> + Fix <function>check_srf_call_placement()</> to handle + <command>VALUES</> cases correctly (Tom Lane) + </para> + + <para> + NEED TEXT. + </para> + </listitem> + + </itemizedlist> + + </sect3> + + <sect3> + <title>Data Types</title> + + <itemizedlist> + + <listitem> +<!-- +2017-03-31 [e306df7f9] Full Text Search support for JSON and JSONB +--> + <para> + Add full text search support for <type>JSON</> and <type>JSONB</> + (Dmitry Dolgov) + </para> + + <para> + This is accessed via <function>ts_headline()</> and + <function>to_tsvector</>. + </para> + </listitem> + + <listitem> +<!-- +2017-03-15 [c7a9fa399] Add support for EUI-64 MAC addresses as macaddr8 +--> + <para> + Add support for <acronym>EUI-64</> <acronym>MAC</> addresses as + <link linkend="datatype-macaddr8"><type>MACADDR8</></> (Haribabu + Kommi) + </para> + + <para> + This complements support for <acronym>EUI-48</> <acronym>MAC</> + addresses as <type>macaddr</>. + </para> + </listitem> + + <listitem> +<!-- +2017-04-06 [321732705] Identity columns +--> + <para> + Add <link linkend="SQL-CREATETABLE">identity columns</> for + assigning a numeric value to columns on insert (Peter Eisentraut) + </para> + + <para> + These are similar to <type>SERIAL</> columns, but are + <acronym>SQL</> standard compliant. + </para> + </listitem> + + <listitem> +<!-- +2016-09-07 [0ab9c56d0] Support renaming an existing value of an enum type. +--> + <para> + Allow <link linkend="datatype-enum"><type>ENUM</></> values to be + renamed (Dagfinn Ilmari Mannsåker) + </para> + + <para> + This uses the syntax <link linkend="SQL-ALTERTYPE"><command>ALTER + TYPE ... RENAME VALUE</></>. + </para> + </listitem> + + <listitem> +<!-- +2017-02-22 [502a3832c] Correctly handle array pseudotypes in to_json and to_jso +--> + <para> + Properly treat array pseudotypes + (<type>anyarray</>) as arrays in <link + linkend="functions-json-creation-table"><function>to_json()</></> + and <function>to_jsonb()</> (Andrew Dunstan) + </para> + + <para> + Previously "anyarray" values were converted to <type>JSON</> + strings. + </para> + </listitem> + + <listitem> +<!-- +2017-01-17 [323b96aa3] Register missing money operators in system catalogs +--> + <para> + Add operators for multiplication and division + of <link linkend="datatype-money"><type>money</></link> values + with <type>int8</> values (Peter Eisentraut) + </para> + + <para> + Previously such cases would result in converting the <type>int8</> + values to <type>float8</> and then using + the <type>money</>-and-<type>float8</> operators. The new behavior + avoids possible precision loss. But note that division + of <type>money</> by <type>int8</> now truncates the quotient, like + other integer-division cases, while the previous behavior would have + rounded. + </para> + </listitem> + + <listitem> +<!-- +2016-09-14 [656df624c] Add overflow checks to money type input function +--> + <para> + More strictly check the <type>money</> type for overflow operations + (Peter Eisentraut) + </para> + </listitem> + + </itemizedlist> + + </sect3> + + <sect3> + <title>Functions</title> + + <itemizedlist> + + <listitem> +<!-- +2016-08-17 [cf9b0fea5] Implement regexp_match(), a simplified alternative to re +--> + <para> + Add simplified <link + linkend="functions-posix-regexp"><function>regexp_match()</></> + function (Emre Hasegeli) + </para> + + <para> + Similar to <function>regexp_matches()</>, but only returns results + from the first match so it is easier use for simple cases. + </para> + </listitem> + + <listitem> +<!-- +2017-01-18 [d00ca333c] Implement array version of jsonb_delete and operator +--> + <para> + Add version of jsonb's <link + linkend="functions-jsonb-op-table">delete operator</> that takes + an array of keys to delete (Magnus Hagander) + </para> + + <para> + The <type>JSONB</> delete operator also now supports arrays. + </para> + </listitem> + + <listitem> +<!-- +2017-04-06 [cf35346e8] Make json_populate_record and friends operate recursivel +--> + <para> + Improve <link + linkend="functions-json-processing-table"><function>json_populate_record</></> + and friends operate recursively (Nikita Glukhov) + </para> + + <para> + CLARIFY + </para> + </listitem> + + <listitem> +<!-- +2016-08-23 [86f31695f] Add txid_current_ifassigned(). +--> + <para> + Add function <link + linkend="functions-txid-snapshot"><function>txid_current_ifassigned()</></> + to return <literal>NULL</> if no transaction id has been assigned + (Craig Ringer) + </para> + + <para> + This is different from <link + linkend="functions-txid-snapshot"><function>txid_current()</></>, + which always returns a transaction id by assigning one if necessary. + This can be also run on standby servers. + </para> + </listitem> + + <listitem> +<!-- +2017-03-24 [857ee8e39] Add a txid_status function. +--> + <para> + Add function <link + linkend="functions-txid-snapshot"><function>txid_status()</></> + to check if a transaction was committed (Craig Ringer) + </para> + + <para> + This is useful for checking after an abrupt disconnection if + your previous transaction committed and you just didn't receive + the acknowledgement. + </para> + </listitem> + + <listitem> +<!-- +2017-01-19 [30bcebbdc] Allow negative years in make_date to represent BC years +--> + <para> + Allow <link + linkend="functions-formatting-table"><function>make_date()</></> + to interpret negative years as <acronym>BC</> years (Álvaro + Herrera) + </para> + </listitem> + + <listitem> +<!-- +2016-09-28 [d3cd36a13] Make to_timestamp() and to_date() range-check fields of +--> + <para> + Have <function>to_timestamp()</> and <function>to_date()</> check + input values for validity (Artur Zakirov) + </para> + + <para> + Previously <function>to_date('2009-06-40','YYYY-MM-DD')</> was + accepted and returned '2009-07-10'. It will now generate an error. + </para> + </listitem> + + </itemizedlist> + + </sect3> + + <sect3> + <title>Server-Side Languages</title> + + <itemizedlist> + + <listitem> +<!-- +2017-03-27 [70ec3f1f8] PL/Python: Add cursor and execute methods to plan object +--> + <para> + Allow the PL/Python plan object to call cursor and execute methods + (Peter Eisentraut) + </para> + + <para> + This is a more object oriented style. + </para> + </listitem> + + <listitem> +<!-- +2016-12-13 [55caaaeba] Improve handling of array elements as getdiag_targets an +--> + <para> + Allow PL/pgSQL's <command>GET DIAGNOSTICS</> to retrieve values + into array elements (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +2016-11-08 [1833f1a1c] Simplify code by getting rid of SPI_push, SPI_pop, SPI_r +--> + <para> + Remove <acronym>SPI</> functions <function>SPI_push()</>, + <function>SPI_pop()</>, <function>SPI_restore_connection()</> + as unnecessary (Tom Lane) + </para> + + <para> + Their functionality now happens automatically. Also, + <function>SPI_palloc()</> now requires an active connection. + </para> + </listitem> + + </itemizedlist> + + <sect4> + <title><link linkend="pltcl">PL/Tcl</></title> + + <itemizedlist> + + <listitem> +<!-- +2016-11-06 [26abb50c4] Support PL/Tcl functions that return composite types and +--> + <para> + Allow PL/Tcl functions to return composite types and sets + (Jim Nasby) + </para> + </listitem> + + <listitem> +<!-- +2017-03-11 [b58fd4a9c] Add a "subtransaction" command to PL/Tcl. +--> + <para> + Add a subtransaction command to PL/Tcl (Victor Wagner) + </para> + + <para> + This allows PL/Tcl queries to fail without aborting the entire + function. + </para> + </listitem> + + <listitem> +<!-- +2017-03-07 [0d2b1f305] Invent start_proc parameters for PL/Tcl. +--> + <para> + Add <acronym>GUC</>s to allow initialization routines to be called + on PL/Tcl startup (Tom Lane) + </para> + + <para> + The <acronym>GUC</>s are <varname>pltcl.start_proc</> and + <varname>pltclu.start_proc</>. + </para> + </listitem> + + </itemizedlist> + + </sect4> + </sect3> + + <sect3> + <title>Client Interfaces</title> + + <itemizedlist> + + <listitem> +<!-- +2016-11-03 [274bb2b38] libpq: Allow connection strings and URIs to specify mult +--> + <para> + Allow libpq to connect to <link + linkend="libpq-connect-host">multiple specified</> host names + (Robert Haas) + </para> + + <para> + libpq will connect with the first responsive host name. + </para> + </listitem> + + <listitem> +<!-- +2016-11-29 [721f7bd3c] libpq: Add target_session_attrs parameter. +--> + <para> + Allow the libpq connection string to request a <link + linkend="libpq-connect-target-session-attrs">read/write host</> + (Victor Wagner, Mithun Cy) + </para> + + <para> + This is useful when multiple libpq host names are + specified, and is controlled by libpq connection parameter + <option>target_session_attrs</>. + </para> + </listitem> + + <listitem> +<!-- +2017-01-24 [ba005f193] Allow password file name to be specified as a libpq conn +--> + <para> + Allow <link linkend="libpq-connect-passfile">password file name</> + to be specified as a libpq connection parameter (Julian Markwort) + </para> + + <para> + Previously this could only be specified via an environment variable. + </para> + </listitem> + + <listitem> +<!-- +2017-05-03 [8f8b9be51] Add PQencryptPasswordConn function to libpq, use it in p +--> + <para> + Add function <link + linkend="libpq-pqencryptpasswordconn"><function>PQencryptPasswordConn()</></> + to allow creation of more types of encrypted passwords on the + client-side (Michael Paquier, Heikki Linnakangas) + </para> + + <para> + Previously only <literal>MD5</> passwords could be created using <link + linkend="libpq-pqencryptpassword"><function>PQencryptPassword()</></>. + This new function can also create <link + linkend="auth-pg-hba-conf"><literal>SCRAM-SHA-256</></> passwords. + </para> + </listitem> + + <listitem> +<!-- +2016-08-16 [a7b5573d6] Remove separate version numbering for ecpg preprocessor. +--> + <para> + ecpg preprocessor version changed from 4.12 to 10 (Tom Lane) + </para> + + <para> + The ecpg version now matches the Postgres distribution version + number. + </para> + </listitem> + + </itemizedlist> + + </sect3> + + <sect3> + <title>Client Applications</title> + + <sect4> + <title><xref linkend="APP-PSQL"></title> + + <itemizedlist> + + <listitem> +<!-- +2017-03-30 [e984ef586] Support \if ... \elif ... \else ... \endif in psql scrip +2017-04-02 [5dbc5da11] Fix behavior of psql's \p to agree with \g, \w, etc. +2017-04-02 [68dba97a4] Document psql's behavior of recalling the previously exe +--> + <para> + Add conditional branch support to <application>psql</> (Corey + Huinker) + </para> + + <para> + The new syntax uses \if, \elif, \else, and \endif. This is + particularly helpful for scripting. + </para> + </listitem> + + <listitem> +<!-- +2017-03-07 [b2678efd4] psql: Add \gx command +--> + <para> + Add <application>psql</> \gx command to perform \g(execute) + in expanded mode (\x) (Christoph Berg) + </para> + </listitem> + + <listitem> +<!-- +2016-11-03 [a0f357e57] psql: Split up "Modifiers" column in \d and \dD +--> + <para> + Improve <application>psql</>'s \d (relation) and \dD (domain) + commands to specify collation, nullable, and default in separate + columns (Peter Eisentraut) + </para> + + <para> + Previous they were in a single "Modifiers" column. + </para> + </listitem> + + <listitem> +<!-- +2017-04-01 [f833c847b] Allow psql variable substitution to occur in backtick co +--> + <para> + Expand <application>psql</> colon variables when used in + backtick-executed contexts (Tom Lane) + </para> + + <para> + This is particularly useful for the new <application>psql</> + conditional branch support commands. + </para> + </listitem> + + <listitem> +<!-- +2017-01-30 [511ae628f] Make psql reject attempts to set special variables to in +2017-02-01 [86322dc7e] Improve psql's behavior for \set and \unset of its contr +2017-02-02 [fd6cd6980] Clean up psql's behavior for a few more control variable +--> + <para> + Prevent <application>psql</> special variables from being set to + invalid values (Daniel Vérité, Tom Lane) + </para> + + <para> + Previously setting <application>psql</> special variables + to invalid values produced the default behavior. \set and + \unset of special variables now sets them to "on" and its + default value, rather than a zero-length string and undefined. + Also have \set always display values for <literal>FETCH_COUNT</>, + <literal>HISTSIZE</>, and <literal>IGNOREEOF</>. + </para> + </listitem> + + <listitem> +<!-- +2016-08-18 [49917dbd7] Improve psql's tab completion for ALTER EXTENSION foo UP +2016-08-18 [8019b5a89] Improve psql's tab completion for \l. +2016-09-01 [76f9dd4fa] Improve tab completion for BEGIN & START|SET TRANSACTION +2016-09-11 [52803098a] psql tab completion for CREATE DATABASE ... TEMPLATE ... +2016-09-12 [63c1a8719] Fix recent commit for tab-completion of database templat +2016-11-03 [1d15d0db5] psql: Tab-complete LOCK [TABLE] ... IN {ACCESS|ROW|SHARE +2016-11-04 [927d7bb6b] Improve tab completion for CREATE TRIGGER. +2016-11-08 [577f0bdd2] psql: Tab completion for renaming enum values. +2017-03-01 [b5a388392] psql: Add tab completion for DEALLOCATE +2017-03-16 [d7d77f382] psql: Add completion for \help DROP|ALTER +--> + <para> + Improve <application>psql</>'s tab completion (Jeff Janes, + Ian Barwick, Andreas Karlsson, Sehrope Sarkuni, Thomas Munro, + Kevin Grittner, Dagfinn Ilmari Mannsåker) + </para> + </listitem> + + </itemizedlist> + + </sect4> + + <sect4> + <title><xref linkend="pgbench"></title> + + <itemizedlist> + + <listitem> +<!-- +2016-11-09 [41124a91e] pgbench: Allow the transaction log file prefix to be cha +--> + <para> + Add pgbench option <option>--log-prefix</> to control the log + file prefix (Masahiko Sawada) + </para> + </listitem> + + <listitem> +<!-- +2017-01-20 [cdc2a7047] Allow backslash line continuations in pgbench's meta com +--> + <para> + Allow pgbench's meta commands to span multiple lines via a + line-terminating backslash (Fabien Coelho) + </para> + </listitem> + + </itemizedlist> + + </sect4> + + </sect3> + + <sect3> + <title>Server Applications</title> + + <itemizedlist> + + <listitem> +<!-- +2017-01-17 [cada1af31] Add compression support to pg_receivexlog +--> + <para> + Add <link + linkend="app-pgreceivewal"><application>pg_receivewal</></> + option <option>-Z</>/<option>--compress</> to support compression + (Michael Paquier) + </para> + </listitem> + + <listitem> +<!-- +2017-01-04 [7c030783a] Add pg_recvlogical -\-endpos=LSN +--> + <para> + Add <link + linkend="app-pgrecvlogical"><application>pg_recvlogical</></> option + (<option>--endpos</>) to specify the ending position (Craig Ringer) + </para> + + <para> + This complements the existing <option>--startpos</> option. + </para> + </listitem> + + <listitem> +<!-- +2016-10-19 [5d58c07a4] initdb pg_basebackup: Rename -\-noxxx options to -\-no-x +--> + <para> + Rename <link linkend="APP-INITDB"><application>initdb</></> + options <option>--noclean</> and <option>--nosync</> to be spelled + <option>--no-clean</> and <option>--no-sync</> (Vik Fearing, + Peter Eisentraut) + </para> + + <para> + The old spellings are still supported. + </para> + </listitem> + + </itemizedlist> + + <sect4> + <title><link linkend="APP-PGDUMP"><application>pg_dump</></>, <link linkend="APP-PG-DUMPALL"><application>pg_dumpall</></>. + <link linkend="APP-PGRESTORE"><application>pg_restore</></></title> + + <itemizedlist> + + <listitem> +<!-- +2016-09-20 [46b55e7f8] pg_restore: Add -N option to exclude schemas +--> + <para> + Allow <application>pg_restore</> to exclude schemas (Michael Banck) + </para> + + <para> + This added a new <option>-N</>/<option>--exclude-schema</> option. + </para> + </listitem> + + <listitem> +<!-- +2016-11-29 [4fafa579b] Add -\-no-blobs option to pg_dump +--> + <para> + Add <option>--no-blobs</> option to + <application>pg_dump</> (Guillaume Lelarge) + </para> + + <para> + This suppresses the dumping of large objects. + </para> + </listitem> + + <listitem> +<!-- +2017-03-07 [9a83d56b3] Allow pg_dumpall to dump roles w/o user passwords +--> + <para> + Add <application>pg_dumpall</> option + <option>--no-role-passwords</> to dump roles without user passwords + (Robins Tharakan, Simon Riggs) + </para> + + <para> + This allows easier dumping for less-privileged users. + </para> + </listitem> + + <listitem> +<!-- +2017-03-22 [96a7128b7] Sync pg_dump and pg_dumpall output +--> + <para> + Issue fsync on the output files generated by + <application>pg_dump</> and + <application>pg_dumpall</> (Michael Paquier) + </para> + + <para> + This can be disabled with the <option>--no-sync</> option. + </para> + </listitem> + + </itemizedlist> + + </sect4> + + <sect4> + + <title><xref linkend="app-pgbasebackup"></title> + + <itemizedlist> + + <listitem> +<!-- +2016-10-23 [56c7d8d45] Allow pg_basebackup to stream transaction log in tar mod +2016-12-21 [ecbdc4c55] Forbid invalid combination of options in pg_basebackup. +--> + <para> + Allow <application>pg_basebackup</> to stream write-ahead log in + tar mode (Magnus Hagander) + </para> + + <para> + The <acronym>WAL</> will be stored in a separate tar file from + the base backup. + </para> + </listitem> + + <listitem> +<!-- +2017-01-16 [e7b020f78] Make pg_basebackup use temporary replication slots +--> + <para> + Make <application>pg_basebackup</> use temporary replication slots + (Magnus Hagander) + </para> + + <para> + Temporary replication slots will be used by default when + <application>pg_basebackup</> uses wal streaming with default + options. + </para> + </listitem> + + <listitem> +<!-- +2016-09-29 [bc34223bc] pg_basebackup pg_receivexlog: Issue fsync more carefully +2016-09-29 [6ed2d8584] pg_basebackup: Add - option +--> + <para> + Improve fsync handling of <application>pg_basebackup</> and + <application>pg_receivewal</> (Michael Paquier) + </para> + + <para> + Also add <option>--nosync</> option to disable fsync. + </para> + </listitem> + + <listitem> +<!-- +2016-09-28 [6ad8ac602] Exclude additional directories in pg_basebackup +--> + <para> + Improve <application>pg_basebackup</>'s handling of which + directories to skip (David Steele) + </para> + + <para> + Also improve the documentation of skipped directories. + </para> + </listitem> + + </itemizedlist> + + </sect4> + + <sect4> + <title><application><xref linkend="app-pg-ctl"></></title> + + <itemizedlist> + + <listitem> +<!-- +2016-09-21 [e7010ce47] pg_ctl: Add wait option to promote action +--> + <para> + Add wait option for <application><xref linkend="app-pg-ctl"></>'s + promote operation (Peter Eisentraut) + </para> + </listitem> + + <listitem> +<!-- +2016-10-19 [0be22457d] pg_ctl: Add long options for -w and -W +--> + <para> + Add long options for <application>pg_ctl</> wait (<option>--wait</>) + and no-wait (<option>--no-wait</>) (Vik Fearing) + </para> + </listitem> + + <listitem> +<!-- +2016-10-19 [caf936b09] pg_ctl: Add long option for -o +--> + <para> + Add long options flag for <application>pg_ctl</> + <literal>options</> (Peter Eisentraut) + </para> + + <para> + It is called <option>--options</>. + </para> + </listitem> + + </itemizedlist> + + </sect4> + </sect3> + + <sect3> + <title>Source Code</title> + + <itemizedlist> + + <listitem> +<!-- +2016-08-15 [ca9112a42] Stamp HEAD as 10devel. +--> + <para> + New major version numbering (Peter Eisentraut, Tom Lane) + </para> + + <para> + Major versions will now increase just the first number, and minor + releases will increase just the second number. A third number + will no longer be used in Postgres version numbers. + </para> + </listitem> + + <listitem> +<!-- +2017-03-23 [eccfef81e] ICU support +--> + <para> + Allow the <link linkend="configure"><acronym>ICU</></> library to + optionally be used for collation support (Peter Eisentraut) + </para> + + <para> + The <acronym>ICU</> library has versioning that allows detection + of collation changes between versions. It is enabled via configure + option <option>--with-icu</>. The default still uses the operating + system's native collation library. + </para> + </listitem> + + <listitem> +<!-- +2016-11-04 [c8ead2a39] Provide DLLEXPORT markers for C functions via PG_FUNCTIO +--> + <para> + Automatically mark all <link + linkend="xfunc-c"><function>PG_FUNCTION_INFO_V1</></> functions + as <literal>DLLEXPORT</>-ed on + <systemitem class="osname">Windows</> (Laurenz Albe) + </para> + + <para> + If third-party code is using <literal>extern</> function + declarations, they should also add <literal>DLLEXPORT</> markers + to those declarations. + </para> + </listitem> + + <listitem> +<!-- +2016-12-02 [13e14a78e] Management of free memory pages. +2016-12-02 [13df76a53] Introduce dynamic shared memory areas. +2016-12-19 [e13029a5c] Provide a DSA area for all parallel queries. +--> + <para> + Allow shared memory to be dynamically allocated (Thomas Munro, + Robert Haas) + </para> + </listitem> + + <listitem> +<!-- +2017-02-27 [58b25e981] Add "Slab" MemoryContext implementation for efficient eq +--> + <para> + Add slab-like memory allocator for efficient fixed-size allocations + (Tomas Vondra) + </para> + </listitem> + + <listitem> +<!-- +2016-10-09 [ecb0d20a9] Use unnamed POSIX semaphores, if available, on Linux and +--> + <para> + Use <acronym>POSIX</> semaphores rather than SysV semaphores + on <systemitem class="osname">Linux</> and <systemitem + class="osname">FreeBSD</> (Tom Lane) + </para> + + <para> + This avoids some limits on SysV semaphore usage. + </para> + </listitem> + + <listitem> +<!-- +2017-04-07 [e8fdbd58f] Improve 64bit atomics support. +--> + <para> + Improve support for 64-bit atomics (Andres Freund) + </para> + </listitem> + + <listitem> +<!-- +2017-03-10 [f8f1430ae] Enable 64 bit atomics on ARM64. +--> + <para> + Enable 64-bit atomic operations on <acronym>ARM64</> (Roman + Shaposhnik) + </para> + </listitem> + + <listitem> +<!-- +2017-01-02 [1d63f7d2d] Use clock_gettime(), if available, in instr_time measure +--> + <para> + Switch to using <function>clock_gettime()</>, if available, for + duration measurements (Tom Lane) + </para> + + <para> + <function>gettimeofday()</> is used if <function>clock_gettime()</> + is not available. + </para> + </listitem> + + <listitem> +<!-- +2016-12-05 [fe0a0b599] Replace PostmasterRandom() with a stronger source, secon +--> + <para> + Add more robust random number generators to be used for + cryptographic secure uses (Magnus Hagander, Michael Paquier, + Heikki Linnakangas) + </para> + + <para> + If no strong random number generator can be found, configure + will fail unless the <link linkend="configure">configure</> + <option>--disable-strong-random</> is used. However, with this + option, pgcrypto functions requiring a strong random number + generator will be disabled. + </para> + </listitem> + + <listitem> +<!-- +2016-08-18 [e8306745e] doc: Speed up XSLT builds +2016-08-24 [0e4cc1fc5] doc: Fix XSLT speedup with older upstream stylesheet ver +--> + <para> + Overhaul documentation <link linkend="docguide-toolsets">build + process</> (Alexander Lakhin, Alexander Law) + </para> + </listitem> + + <listitem> +<!-- +2017-04-06 [510074f9f] Remove use of Jade and DSSSL +--> + <para> + Use <acronym>XSLT</> to build the Postgres documentation (Peter + Eisentraut) + </para> + + <para> + Previously <application>Jade</>, <acronym>DSSSL,</> and + <application>JadeTex</> were used. + </para> + </listitem> + + <listitem> +<!-- +2016-11-15 [e36ddab11] Build HTML documentation using XSLT stylesheets by defau +--> + <para> + Build <acronym>HTML</> documentation using <acronym>XSLT</> + stylesheets by default (Peter Eisentraut) + </para> + </listitem> + + </itemizedlist> + + </sect3> + + <sect3> + <title>Additional Modules</title> + + <itemizedlist> + + <listitem> +<!-- +2016-09-29 [8e91e12bc] Allow contrib/file_fdw to read from a program, like COPY +--> + <para> + Allow <link linkend="file-fdw"><application>file_fdw</></> to read + from program output as well as files (Corey Huinker, Adam Gomaa) + </para> + </listitem> + + <listitem> +<!-- +2016-10-21 [7012b132d] postgres_fdw: Push down aggregates to remote servers. +2017-04-24 [332bec1e6] postgres_fdw: Fix join push down with extensions +--> + <para> + Push aggregates to foreign data wrapper servers, where possible + (Jeevan Chalke, Ashutosh Bapat) + </para> + + <para> + This reduces the amount of data that must be passed + from the foreign data wrapper server, and offloads + aggregate computation from the requesting server. The <link + linkend="postgres-fdw"><application>postgres_fdw</></> is able to + perform this optimization. There are also improvements in + pushing down joins involving extensions. + </para> + </listitem> + + <listitem> +<!-- +2017-03-16 [b30fb56b0] postgres_fdw: Push down FULL JOINs with restriction clau +--> + <para> + Allow push down of <literal>FULL JOIN</> queries containing + subqueries in the + <literal>FROM</> clause to foreign servers (Etsuro Fujita) + </para> + </listitem> + + <listitem> +<!-- +2016-08-26 [ae025a159] Support OID system column in postgres_fdw. +--> + <para> + Properly support <type>OID</> columns in + <application>postgres_fdw</> tables (Etsuro Fujita) + </para> + + <para> + Previously <type>OID</> columns always returned zeros. + </para> + </listitem> + + <listitem> +<!-- +2017-03-21 [f7946a92b] Add btree_gist support for enum types. +--> + <para> + Allow <link linkend="btree-gist"><application>btree_gist</></> + and <link linkend="btree-gin"><application>btree_gin</></> to + index enum types (Andrew Dunstan) + </para> + + <para> + This allows enums to be used in exclusion constraints. + </para> + </listitem> + + <listitem> +<!-- +2016-11-29 [11da83a0e] Add uuid to the set of types supported by contrib/btree_ +--> + <para> + Add indexing support to <application>btree_gist</> for the + <type>UUID</> data type (Paul Jungwirth) + </para> + </listitem> + + <listitem> +<!-- +2017-03-09 [3717dc149] Add amcheck extension to contrib. +--> + <para> + Add <link linkend="amcheck"><application>amcheck</></> which can + check the validity of btree indexes (Peter Geoghegan) + </para> + </listitem> + + <listitem> +<!-- +2017-03-27 [a6f22e835] Show ignored constants as "$N" rather than "?" in pg_sta +--> + <para> + Show ignored constants as <literal>$N</> rather than <literal>?</> + in + <link + linkend="pgstatstatements"><application>pg_stat_statements</></> + (Lukas Fittl) + </para> + </listitem> + + <listitem> +<!-- +2016-09-27 [f31a931fa] Improve contrib/cube's handling of zero-D cubes, infinit +--> + <para> + Improve <link linkend="cube"><application>cube</></>'s handling + of zero-dimensional cubes (Tom Lane) + </para> + + <para> + This also improves handling of <literal>infinite</> and + <literal>NaN</> values. + </para> + </listitem> + + <listitem> +<!-- +2016-09-29 [6e654546f] Don't bother to lock bufmgr partitions in pg_buffercache +--> + <para> + Allow <link + linkend="pgbuffercache"><application>pg_buffercache</></> to run + with fewer locks (Ivan Kartyshov) + </para> + + <para> + This allows it be less disruptive when run on production systems. + </para> + </listitem> + + <listitem> +<!-- +2017-02-03 [e759854a0] pgstattuple: Add pgstathashindex. +--> + <para> + Add <function>pgstathashindex()</> function to <link + linkend="pgstattuple"><application>pgstattuple</></> to view hash + index statistics (Ashutosh Sharma) + </para> + </listitem> + + <listitem> +<!-- +2016-09-29 [fd321a1df] Remove superuser checks in pgstattuple +--> + <para> + Allow <link linkend="pgstattuple"><application>pgstattuple</></> + to use <command>GRANT</> permissions (Stephen Frost) + </para> + + <para> + This allows non-superusers to run these functions if permissions + allow. + </para> + </listitem> + + <listitem> +<!-- +2016-10-28 [d4b5d4cad] pgstattuple: Don't take heavyweight locks when examining +--> + <para> + Reduce locking when <link + linkend="pgstattuple"><application>pgstattuple</></> examines hash + indexes (Amit Kapila) + </para> + </listitem> + + <listitem> +<!-- +2017-03-17 [fef2bcdcb] pageinspect: Add page_checksum function +--> + <para> + Add <function>page_checksum()</> function to <link + linkend="pageinspect"><application>pageinspect</></> (Tomas Vondra) + </para> + </listitem> + + <listitem> +<!-- +2017-02-02 [08bf6e529] pageinspect: Support hash indexes. +--> + <para> + Add hash index support to <link + linkend="pageinspect"><application>pageinspect</></> (Jesper + Pedersen, Ashutosh Sharma) + </para> + </listitem> + + <listitem> +<!-- +2017-04-04 [193f5f9e9] pageinspect: Add bt_page_items function with bytea argum +--> + <para> + Add <link linkend="pageinspect"><application>pageinspect</></> + function <function>bt_page_items()</> to print page items from a + page image (Tomas Vondra) + </para> + + <para> + Previously only block numbers were supported. + </para> + </listitem> + + </itemizedlist> + + </sect3> + + </sect2> + + </sect1> diff --git a/doc/src/sgml/release-7.4.sgml b/doc/src/sgml/release-7.4.sgml index 5a4c52d4c2..bc4f4e18d0 100644 --- a/doc/src/sgml/release-7.4.sgml +++ b/doc/src/sgml/release-7.4.sgml @@ -4,10 +4,10 @@ <sect1 id="release-7-4-30"> <title>Release 7.4.30</title> - <note> - <title>Release Date</title> - <simpara>2010-10-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-10-04</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.29. @@ -138,10 +138,10 @@ <sect1 id="release-7-4-29"> <title>Release 7.4.29</title> - <note> - <title>Release Date</title> - <simpara>2010-05-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-05-17</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.28. @@ -242,14 +242,14 @@ <listitem> <para> - Update pl/perl's <filename>ppport.h</> for modern Perl versions + Update PL/Perl's <filename>ppport.h</> for modern Perl versions (Andrew) </para> </listitem> <listitem> <para> - Fix assorted memory leaks in pl/python (Andreas Freund, Tom) + Fix assorted memory leaks in PL/Python (Andreas Freund, Tom) </para> </listitem> @@ -268,7 +268,7 @@ </para> <para> - This behavior has been observed on BSD-derived kernels including OS X. + This behavior has been observed on BSD-derived kernels including macOS. It resulted in an entirely-misleading startup failure complaining that the shared memory request size was too large. </para> @@ -282,10 +282,10 @@ <sect1 id="release-7-4-28"> <title>Release 7.4.28</title> - <note> - <title>Release Date</title> - <simpara>2010-03-15</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-03-15</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.27. @@ -401,10 +401,10 @@ <sect1 id="release-7-4-27"> <title>Release 7.4.27</title> - <note> - <title>Release Date</title> - <simpara>2009-12-14</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-12-14</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.26. @@ -521,10 +521,10 @@ <sect1 id="release-7-4-26"> <title>Release 7.4.26</title> - <note> - <title>Release Date</title> - <simpara>2009-09-09</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-09-09</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.25. @@ -651,10 +651,10 @@ <sect1 id="release-7-4-25"> <title>Release 7.4.25</title> - <note> - <title>Release Date</title> - <simpara>2009-03-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-03-16</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.24. @@ -731,10 +731,10 @@ <sect1 id="release-7-4-24"> <title>Release 7.4.24</title> - <note> - <title>Release Date</title> - <simpara>2009-02-02</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-02-02</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.23. @@ -817,10 +817,10 @@ <sect1 id="release-7-4-23"> <title>Release 7.4.23</title> - <note> - <title>Release Date</title> - <simpara>2008-11-03</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-11-03</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.22. @@ -901,10 +901,10 @@ <sect1 id="release-7-4-22"> <title>Release 7.4.22</title> - <note> - <title>Release Date</title> - <simpara>2008-09-22</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-09-22</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.21. @@ -977,10 +977,10 @@ <sect1 id="release-7-4-21"> <title>Release 7.4.21</title> - <note> - <title>Release Date</title> - <simpara>2008-06-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-06-12</para> + </formalpara> <para> This release contains one serious bug fix over 7.4.20. @@ -1031,10 +1031,10 @@ <sect1 id="release-7-4-20"> <title>Release 7.4.20</title> - <note> - <title>Release Date</title> - <simpara>never released</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>never released</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.19. @@ -1176,10 +1176,10 @@ <sect1 id="release-7-4-19"> <title>Release 7.4.19</title> - <note> - <title>Release Date</title> - <simpara>2008-01-07</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-01-07</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.18, @@ -1330,10 +1330,10 @@ <sect1 id="release-7-4-18"> <title>Release 7.4.18</title> - <note> - <title>Release Date</title> - <simpara>2007-09-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-09-17</para> + </formalpara> <para> This release contains fixes from 7.4.17. @@ -1406,10 +1406,10 @@ <sect1 id="release-7-4-17"> <title>Release 7.4.17</title> - <note> - <title>Release Date</title> - <simpara>2007-04-23</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-04-23</para> + </formalpara> <para> This release contains fixes from 7.4.16, @@ -1477,10 +1477,10 @@ <sect1 id="release-7-4-16"> <title>Release 7.4.16</title> - <note> - <title>Release Date</title> - <simpara>2007-02-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-02-05</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.15, including @@ -1548,10 +1548,10 @@ <sect1 id="release-7-4-15"> <title>Release 7.4.15</title> - <note> - <title>Release Date</title> - <simpara>2007-01-08</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-01-08</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.14. @@ -1637,10 +1637,10 @@ <sect1 id="release-7-4-14"> <title>Release 7.4.14</title> - <note> - <title>Release Date</title> - <simpara>2006-10-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-10-16</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.13. @@ -1684,10 +1684,10 @@ ANYARRAY</para></listitem> <sect1 id="release-7-4-13"> <title>Release 7.4.13</title> - <note> - <title>Release Date</title> - <simpara>2006-05-23</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-05-23</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.12, @@ -1791,10 +1791,10 @@ Fuhr)</para></listitem> <sect1 id="release-7-4-12"> <title>Release 7.4.12</title> - <note> - <title>Release Date</title> - <simpara>2006-02-14</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-02-14</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.11. @@ -1854,10 +1854,10 @@ and <function>isinf</> during configure (Tom)</para></listitem> <sect1 id="release-7-4-11"> <title>Release 7.4.11</title> - <note> - <title>Release Date</title> - <simpara>2006-01-09</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-01-09</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.10. @@ -1921,10 +1921,10 @@ what's actually returned by the query (Joe)</para></listitem> <sect1 id="release-7-4-10"> <title>Release 7.4.10</title> - <note> - <title>Release Date</title> - <simpara>2005-12-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-12-12</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.9. @@ -1974,10 +1974,10 @@ table has been dropped</para></listitem> <sect1 id="release-7-4-9"> <title>Release 7.4.9</title> - <note> - <title>Release Date</title> - <simpara>2005-10-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-10-04</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.8. @@ -2043,10 +2043,10 @@ code</para></listitem> <sect1 id="release-7-4-8"> <title>Release 7.4.8</title> - <note> - <title>Release Date</title> - <simpara>2005-05-09</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-05-09</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.7, including several @@ -2227,10 +2227,10 @@ holder of the lock released it within a very narrow window. <sect1 id="release-7-4-7"> <title>Release 7.4.7</title> - <note> - <title>Release Date</title> - <simpara>2005-01-31</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-01-31</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.6, including several @@ -2287,10 +2287,10 @@ GMT</para></listitem> <sect1 id="release-7-4-6"> <title>Release 7.4.6</title> - <note> - <title>Release Date</title> - <simpara>2004-10-22</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2004-10-22</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.5. @@ -2359,10 +2359,10 @@ ECPG prepare statement</para></listitem> <sect1 id="release-7-4-5"> <title>Release 7.4.5</title> - <note> - <title>Release Date</title> - <simpara>2004-08-18</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2004-08-18</para> + </formalpara> <para> This release contains one serious bug fix over 7.4.4. @@ -2397,10 +2397,10 @@ still worth a re-release. The bug does not exist in pre-7.4 releases. <sect1 id="release-7-4-4"> <title>Release 7.4.4</title> - <note> - <title>Release Date</title> - <simpara>2004-08-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2004-08-16</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.3. @@ -2437,7 +2437,7 @@ aggregate plan</para></listitem> <listitem><para>Pretty-print UNION queries correctly</para></listitem> <listitem><para>Make psql handle <literal>\r\n</> newlines properly in COPY IN</para></listitem> <listitem><para><application>pg_dump</> handled ACLs with grant options incorrectly</para></listitem> -<listitem><para>Fix thread support for OS X and Solaris</para></listitem> +<listitem><para>Fix thread support for macOS and Solaris</para></listitem> <listitem><para>Updated JDBC driver (build 215) with various fixes</para></listitem> <listitem><para>ECPG fixes</para></listitem> <listitem><para>Translation updates (various contributors)</para></listitem> @@ -2449,10 +2449,10 @@ aggregate plan</para></listitem> <sect1 id="release-7-4-3"> <title>Release 7.4.3</title> - <note> - <title>Release Date</title> - <simpara>2004-06-14</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2004-06-14</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.2. @@ -2507,10 +2507,10 @@ names from outer query levels. <sect1 id="release-7-4-2"> <title>Release 7.4.2</title> - <note> - <title>Release Date</title> - <simpara>2004-03-08</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2004-03-08</para> + </formalpara> <para> This release contains a variety of fixes from 7.4.1. @@ -2614,7 +2614,7 @@ UPDATE pg_database SET datallowconn = false WHERE datname = 'template0'; </para> <itemizedlist> -<listitem><para>Fix <structname>pg_statistics</> alignment bug that could crash optimizer</para> +<listitem><para>Fix <structname>pg_statistic</> alignment bug that could crash optimizer</para> <para>See above for details about this problem.</para></listitem> <listitem><para>Allow non-super users to update <structname>pg_settings</></para></listitem> <listitem><para>Fix several optimizer bugs, most of which led to @@ -2627,7 +2627,7 @@ memory</> error during <command>COPY IN</></para></listitem> TABLE AS</> from tables without OIDs</para></listitem> <listitem><para>Fix problems with <filename>alter_table</> regression test during parallel testing</para></listitem> -<listitem><para>Fix problems with hitting open file limit, especially on OS X (Tom)</para></listitem> +<listitem><para>Fix problems with hitting open file limit, especially on macOS (Tom)</para></listitem> <listitem><para>Partial fix for Turkish-locale issues</para> <para>initdb will succeed now in Turkish locale, but there are still some inconveniences associated with the <literal>i/I</> problem.</para></listitem> @@ -2650,10 +2650,10 @@ inconveniences associated with the <literal>i/I</> problem.</para></listitem> <sect1 id="release-7-4-1"> <title>Release 7.4.1</title> - <note> - <title>Release Date</title> - <simpara>2003-12-22</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2003-12-22</para> + </formalpara> <para> This release contains a variety of fixes from 7.4. @@ -2764,10 +2764,10 @@ DROP SCHEMA information_schema CASCADE; <sect1 id="release-7-4"> <title>Release 7.4</title> - <note> - <title>Release Date</title> - <simpara>2003-11-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2003-11-17</para> + </formalpara> <sect2> <title>Overview</title> @@ -3256,7 +3256,7 @@ DROP SCHEMA information_schema CASCADE; </para> </listitem> - <listitem><para>Enable PAM for Mac OS X (Aaron Hillegass)</para></listitem> + <listitem><para>Enable PAM for macOS (Aaron Hillegass)</para></listitem> <listitem> <para>Make B-tree indexes fully WAL-safe (Tom)</para> @@ -3539,9 +3539,9 @@ DROP SCHEMA information_schema CASCADE; </listitem> <listitem> - <para>Add Mac OS X Rendezvous server support (Chris Campbell)</para> + <para>Add macOS Rendezvous server support (Chris Campbell)</para> <para> - This allows Mac OS X hosts to query the network for available + This allows macOS hosts to query the network for available <productname>PostgreSQL</productname> servers. </para> </listitem> @@ -4561,7 +4561,7 @@ DROP SCHEMA information_schema CASCADE; <listitem><para>Fix locking code for s390x CPU (64-bit) (Tom)</para></listitem> <listitem><para>Allow OpenBSD to use local ident credentials (William Ahern)</para></listitem> <listitem><para>Make query plan trees read-only to executor (Tom)</para></listitem> - <listitem><para>Add Darwin startup scripts (David Wheeler)</para></listitem> + <listitem><para>Add macOS startup scripts (David Wheeler)</para></listitem> <listitem><para>Allow libpq to compile with Borland C++ compiler (Lester Godwin, Karl Waclawek)</para></listitem> <listitem><para>Use our own version of <function>getopt_long()</function> if needed (Peter)</para></listitem> <listitem><para>Convert administration scripts to C (Peter)</para></listitem> diff --git a/doc/src/sgml/release-8.0.sgml b/doc/src/sgml/release-8.0.sgml index 299c34e0f0..0f43e24b1d 100644 --- a/doc/src/sgml/release-8.0.sgml +++ b/doc/src/sgml/release-8.0.sgml @@ -4,10 +4,10 @@ <sect1 id="release-8-0-26"> <title>Release 8.0.26</title> - <note> - <title>Release Date</title> - <simpara>2010-10-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-10-04</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.25. @@ -208,10 +208,10 @@ <sect1 id="release-8-0-25"> <title>Release 8.0.25</title> - <note> - <title>Release Date</title> - <simpara>2010-05-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-05-17</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.24. @@ -312,14 +312,14 @@ <listitem> <para> - Update pl/perl's <filename>ppport.h</> for modern Perl versions + Update PL/Perl's <filename>ppport.h</> for modern Perl versions (Andrew) </para> </listitem> <listitem> <para> - Fix assorted memory leaks in pl/python (Andreas Freund, Tom) + Fix assorted memory leaks in PL/Python (Andreas Freund, Tom) </para> </listitem> @@ -345,7 +345,7 @@ </para> <para> - This behavior has been observed on BSD-derived kernels including OS X. + This behavior has been observed on BSD-derived kernels including macOS. It resulted in an entirely-misleading startup failure complaining that the shared memory request size was too large. </para> @@ -368,10 +368,10 @@ <sect1 id="release-8-0-24"> <title>Release 8.0.24</title> - <note> - <title>Release Date</title> - <simpara>2010-03-15</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-03-15</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.23. @@ -545,10 +545,10 @@ <sect1 id="release-8-0-23"> <title>Release 8.0.23</title> - <note> - <title>Release Date</title> - <simpara>2009-12-14</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-12-14</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.22. @@ -700,10 +700,10 @@ <sect1 id="release-8-0-22"> <title>Release 8.0.22</title> - <note> - <title>Release Date</title> - <simpara>2009-09-09</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-09-09</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.21. @@ -864,10 +864,10 @@ <sect1 id="release-8-0-21"> <title>Release 8.0.21</title> - <note> - <title>Release Date</title> - <simpara>2009-03-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-03-16</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.20. @@ -944,10 +944,10 @@ <sect1 id="release-8-0-20"> <title>Release 8.0.20</title> - <note> - <title>Release Date</title> - <simpara>2009-02-02</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-02-02</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.19. @@ -1030,10 +1030,10 @@ <sect1 id="release-8-0-19"> <title>Release 8.0.19</title> - <note> - <title>Release Date</title> - <simpara>2008-11-03</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-11-03</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.18. @@ -1141,10 +1141,10 @@ <sect1 id="release-8-0-18"> <title>Release 8.0.18</title> - <note> - <title>Release Date</title> - <simpara>2008-09-22</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-09-22</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.17. @@ -1275,10 +1275,10 @@ <sect1 id="release-8-0-17"> <title>Release 8.0.17</title> - <note> - <title>Release Date</title> - <simpara>2008-06-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-06-12</para> + </formalpara> <para> This release contains one serious bug fix over 8.0.16. @@ -1329,10 +1329,10 @@ <sect1 id="release-8-0-16"> <title>Release 8.0.16</title> - <note> - <title>Release Date</title> - <simpara>never released</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>never released</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.15. @@ -1566,10 +1566,10 @@ <sect1 id="release-8-0-15"> <title>Release 8.0.15</title> - <note> - <title>Release Date</title> - <simpara>2008-01-07</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-01-07</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.14, @@ -1715,7 +1715,7 @@ <para> While this could theoretically happen anywhere, no standard build of - Perl did things this way ... until <productname>Mac OS X</> 10.5. + Perl did things this way ... until <productname>macOS</> 10.5. </para> </listitem> @@ -1782,10 +1782,10 @@ <sect1 id="release-8-0-14"> <title>Release 8.0.14</title> - <note> - <title>Release Date</title> - <simpara>2007-09-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-09-17</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.13. @@ -1890,10 +1890,10 @@ <sect1 id="release-8-0-13"> <title>Release 8.0.13</title> - <note> - <title>Release Date</title> - <simpara>2007-04-23</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-04-23</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.12, @@ -1967,10 +1967,10 @@ <sect1 id="release-8-0-12"> <title>Release 8.0.12</title> - <note> - <title>Release Date</title> - <simpara>2007-02-07</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-02-07</para> + </formalpara> <para> This release contains one fix from 8.0.11. @@ -2009,10 +2009,10 @@ <sect1 id="release-8-0-11"> <title>Release 8.0.11</title> - <note> - <title>Release Date</title> - <simpara>2007-02-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-02-05</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.10, including @@ -2080,10 +2080,10 @@ <sect1 id="release-8-0-10"> <title>Release 8.0.10</title> - <note> - <title>Release Date</title> - <simpara>2007-01-08</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-01-08</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.9. @@ -2199,10 +2199,10 @@ <sect1 id="release-8-0-9"> <title>Release 8.0.9</title> - <note> - <title>Release Date</title> - <simpara>2006-10-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-10-16</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.8. @@ -2255,10 +2255,10 @@ Wieland)</para></listitem> <sect1 id="release-8-0-8"> <title>Release 8.0.8</title> - <note> - <title>Release Date</title> - <simpara>2006-05-23</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-05-23</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.7, @@ -2369,10 +2369,10 @@ Fuhr)</para></listitem> <sect1 id="release-8-0-7"> <title>Release 8.0.7</title> - <note> - <title>Release Date</title> - <simpara>2006-02-14</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-02-14</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.6. @@ -2439,9 +2439,9 @@ when the data directory is not specified (Magnus)</para></listitem> (Neil)</para></listitem> <listitem><para>Recover properly if error occurs during argument passing -in <application>PL/python</> (Neil)</para></listitem> +in <application>PL/Python</> (Neil)</para></listitem> -<listitem><para>Fix <application>PL/perl</>'s handling of locales on +<listitem><para>Fix <application>PL/Perl</>'s handling of locales on Win32 to match the backend (Andrew)</para></listitem> <listitem><para>Fix crash when <literal>log_min_messages</> is set to @@ -2449,7 +2449,7 @@ Win32 to match the backend (Andrew)</para></listitem> (Bruce)</para></listitem> <listitem><para>Fix <application>pgxs</> <literal>-L</> library path -specification for Win32, Cygwin, OS X, AIX (Bruce)</para></listitem> +specification for Win32, Cygwin, macOS, AIX (Bruce)</para></listitem> <listitem><para>Check that SID is enabled while checking for Win32 admin privileges (Magnus)</para></listitem> @@ -2468,10 +2468,10 @@ and <function>isinf</> during configure (Tom)</para></listitem> <sect1 id="release-8-0-6"> <title>Release 8.0.6</title> - <note> - <title>Release Date</title> - <simpara>2006-01-09</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-01-09</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.5. @@ -2553,10 +2553,10 @@ what's actually returned by the query (Joe)</para></listitem> <sect1 id="release-8-0-5"> <title>Release 8.0.5</title> - <note> - <title>Release Date</title> - <simpara>2005-12-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-12-12</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.4. @@ -2635,10 +2635,10 @@ to subquery results</para></listitem> <sect1 id="release-8-0-4"> <title>Release 8.0.4</title> - <note> - <title>Release Date</title> - <simpara>2005-10-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-10-04</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.3. @@ -2732,10 +2732,10 @@ code</para></listitem> <sect1 id="release-8-0-3"> <title>Release 8.0.3</title> - <note> - <title>Release Date</title> - <simpara>2005-05-09</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-05-09</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.2, including several @@ -2852,10 +2852,10 @@ data types</para></listitem> <sect1 id="release-8-0-2"> <title>Release 8.0.2</title> - <note> - <title>Release Date</title> - <simpara>2005-04-07</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-04-07</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.1. @@ -3009,10 +3009,10 @@ addresses in <type>INET</> data types (Tom)</para></listitem> <sect1 id="release-8-0-1"> <title>Release 8.0.1</title> - <note> - <title>Release Date</title> - <simpara>2005-01-31</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-01-31</para> + </formalpara> <para> This release contains a variety of fixes from 8.0.0, including several @@ -3078,10 +3078,10 @@ typedefs (Michael)</para></listitem> <sect1 id="release-8-0"> <title>Release 8.0</title> - <note> - <title>Release Date</title> - <simpara>2005-01-19</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-01-19</para> + </formalpara> <sect2> <title>Overview</title> @@ -5224,7 +5224,7 @@ typedefs (Michael)</para></listitem> <listitem> <para> - Improvements to the Mac OS X startup scripts (Ray A.) + Improvements to the macOS startup scripts (Ray A.) </para> </listitem> @@ -5328,7 +5328,7 @@ typedefs (Michael)</para></listitem> <listitem> <para> - Make libpq and ECPG build as proper shared libraries on OS X (Tom) + Make libpq and ECPG build as proper shared libraries on macOS (Tom) </para> </listitem> diff --git a/doc/src/sgml/release-8.1.sgml b/doc/src/sgml/release-8.1.sgml index 0cb5587e9b..d48bccd17d 100644 --- a/doc/src/sgml/release-8.1.sgml +++ b/doc/src/sgml/release-8.1.sgml @@ -4,10 +4,10 @@ <sect1 id="release-8-1-23"> <title>Release 8.1.23</title> - <note> - <title>Release Date</title> - <simpara>2010-12-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-12-16</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.22. @@ -223,10 +223,10 @@ <sect1 id="release-8-1-22"> <title>Release 8.1.22</title> - <note> - <title>Release Date</title> - <simpara>2010-10-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-10-04</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.21. @@ -441,10 +441,10 @@ <sect1 id="release-8-1-21"> <title>Release 8.1.21</title> - <note> - <title>Release Date</title> - <simpara>2010-05-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-05-17</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.20. @@ -539,14 +539,14 @@ <listitem> <para> - Update pl/perl's <filename>ppport.h</> for modern Perl versions + Update PL/Perl's <filename>ppport.h</> for modern Perl versions (Andrew) </para> </listitem> <listitem> <para> - Fix assorted memory leaks in pl/python (Andreas Freund, Tom) + Fix assorted memory leaks in PL/Python (Andreas Freund, Tom) </para> </listitem> @@ -572,7 +572,7 @@ </para> <para> - This behavior has been observed on BSD-derived kernels including OS X. + This behavior has been observed on BSD-derived kernels including macOS. It resulted in an entirely-misleading startup failure complaining that the shared memory request size was too large. </para> @@ -595,10 +595,10 @@ <sect1 id="release-8-1-20"> <title>Release 8.1.20</title> - <note> - <title>Release Date</title> - <simpara>2010-03-15</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-03-15</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.19. @@ -785,10 +785,10 @@ <sect1 id="release-8-1-19"> <title>Release 8.1.19</title> - <note> - <title>Release Date</title> - <simpara>2009-12-14</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-12-14</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.18. @@ -966,10 +966,10 @@ <sect1 id="release-8-1-18"> <title>Release 8.1.18</title> - <note> - <title>Release Date</title> - <simpara>2009-09-09</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-09-09</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.17. @@ -1130,10 +1130,10 @@ <sect1 id="release-8-1-17"> <title>Release 8.1.17</title> - <note> - <title>Release Date</title> - <simpara>2009-03-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-03-16</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.16. @@ -1253,10 +1253,10 @@ <sect1 id="release-8-1-16"> <title>Release 8.1.16</title> - <note> - <title>Release Date</title> - <simpara>2009-02-02</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-02-02</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.15. @@ -1373,10 +1373,10 @@ <sect1 id="release-8-1-15"> <title>Release 8.1.15</title> - <note> - <title>Release Date</title> - <simpara>2008-11-03</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-11-03</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.14. @@ -1525,10 +1525,10 @@ <sect1 id="release-8-1-14"> <title>Release 8.1.14</title> - <note> - <title>Release Date</title> - <simpara>2008-09-22</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-09-22</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.13. @@ -1701,10 +1701,10 @@ <sect1 id="release-8-1-13"> <title>Release 8.1.13</title> - <note> - <title>Release Date</title> - <simpara>2008-06-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-06-12</para> + </formalpara> <para> This release contains one serious and one minor bug fix over 8.1.12. @@ -1768,10 +1768,10 @@ <sect1 id="release-8-1-12"> <title>Release 8.1.12</title> - <note> - <title>Release Date</title> - <simpara>never released</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>never released</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.11. @@ -2018,10 +2018,10 @@ <sect1 id="release-8-1-11"> <title>Release 8.1.11</title> - <note> - <title>Release Date</title> - <simpara>2008-01-07</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-01-07</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.10, @@ -2188,7 +2188,7 @@ <para> While this could theoretically happen anywhere, no standard build of - Perl did things this way ... until <productname>Mac OS X</> 10.5. + Perl did things this way ... until <productname>macOS</> 10.5. </para> </listitem> @@ -2270,10 +2270,10 @@ <sect1 id="release-8-1-10"> <title>Release 8.1.10</title> - <note> - <title>Release Date</title> - <simpara>2007-09-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-09-17</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.9. @@ -2391,10 +2391,10 @@ <sect1 id="release-8-1-9"> <title>Release 8.1.9</title> - <note> - <title>Release Date</title> - <simpara>2007-04-23</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-04-23</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.8, @@ -2482,10 +2482,10 @@ <sect1 id="release-8-1-8"> <title>Release 8.1.8</title> - <note> - <title>Release Date</title> - <simpara>2007-02-07</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-02-07</para> + </formalpara> <para> This release contains one fix from 8.1.7. @@ -2524,10 +2524,10 @@ <sect1 id="release-8-1-7"> <title>Release 8.1.7</title> - <note> - <title>Release Date</title> - <simpara>2007-02-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-02-05</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.6, including @@ -2626,10 +2626,10 @@ <sect1 id="release-8-1-6"> <title>Release 8.1.6</title> - <note> - <title>Release Date</title> - <simpara>2007-01-08</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-01-08</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.5. @@ -2730,7 +2730,7 @@ <listitem> <para> - Fix for Darwin (OS X) compilation (Tom) + Fix for macOS (Darwin) compilation (Tom) </para> </listitem> @@ -2776,10 +2776,10 @@ <sect1 id="release-8-1-5"> <title>Release 8.1.5</title> - <note> - <title>Release Date</title> - <simpara>2006-10-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-10-16</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.4. @@ -2853,10 +2853,10 @@ compilers (Hiroshi Saito)</para></listitem> <sect1 id="release-8-1-4"> <title>Release 8.1.4</title> - <note> - <title>Release Date</title> - <simpara>2006-05-23</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-05-23</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.3, @@ -3007,10 +3007,10 @@ documented (Tom)</para></listitem> <sect1 id="release-8-1-3"> <title>Release 8.1.3</title> - <note> - <title>Release Date</title> - <simpara>2006-02-14</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-02-14</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.2, @@ -3089,12 +3089,12 @@ when the data directory is not specified (Magnus)</para></listitem> together in function result type declarations</para></listitem> <listitem><para>Recover properly if error occurs during argument passing -in <application>PL/python</> (Neil)</para></listitem> +in <application>PL/Python</> (Neil)</para></listitem> <listitem><para>Fix memory leak in <function>plperl_return_next</> (Neil)</para></listitem> -<listitem><para>Fix <application>PL/perl</>'s handling of locales on +<listitem><para>Fix <application>PL/Perl</>'s handling of locales on Win32 to match the backend (Andrew)</para></listitem> <listitem><para>Various optimizer fixes (Tom)</para></listitem> @@ -3104,7 +3104,7 @@ Win32 to match the backend (Andrew)</para></listitem> (Bruce)</para></listitem> <listitem><para>Fix <application>pgxs</> <literal>-L</> library path -specification for Win32, Cygwin, OS X, AIX (Bruce)</para></listitem> +specification for Win32, Cygwin, macOS, AIX (Bruce)</para></listitem> <listitem><para>Check that SID is enabled while checking for Win32 admin privileges (Magnus)</para></listitem> @@ -3129,10 +3129,10 @@ creation (Tom)</para></listitem> <sect1 id="release-8-1-2"> <title>Release 8.1.2</title> - <note> - <title>Release Date</title> - <simpara>2006-01-09</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-01-09</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.1. @@ -3232,10 +3232,10 @@ what's actually returned by the query (Joe)</para></listitem> <sect1 id="release-8-1-1"> <title>Release 8.1.1</title> - <note> - <title>Release Date</title> - <simpara>2005-12-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-12-12</para> + </formalpara> <para> This release contains a variety of fixes from 8.1.0. @@ -3324,10 +3324,10 @@ DISTINCT query</para></listitem> <sect1 id="release-8-1"> <title>Release 8.1</title> - <note> - <title>Release Date</title> - <simpara>2005-11-08</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-11-08</para> + </formalpara> <sect2> <title>Overview</title> @@ -5225,7 +5225,7 @@ SELECT CURRENT_TIMESTAMP AT TIME ZONE 'Europe/London'; <listitem> <para> Add support for <literal>fsync_writethrough</literal> on - Darwin (Chris Campbell) + macOS (Chris Campbell) </para> </listitem> diff --git a/doc/src/sgml/release-8.2.sgml b/doc/src/sgml/release-8.2.sgml index 7f6a74bac9..c00cbd3467 100644 --- a/doc/src/sgml/release-8.2.sgml +++ b/doc/src/sgml/release-8.2.sgml @@ -4,10 +4,10 @@ <sect1 id="release-8-2-23"> <title>Release 8.2.23</title> - <note> - <title>Release Date</title> - <simpara>2011-12-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-12-05</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.22. @@ -232,10 +232,10 @@ <sect1 id="release-8-2-22"> <title>Release 8.2.22</title> - <note> - <title>Release Date</title> - <simpara>2011-09-26</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-09-26</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.21. @@ -539,10 +539,10 @@ <sect1 id="release-8-2-21"> <title>Release 8.2.21</title> - <note> - <title>Release Date</title> - <simpara>2011-04-18</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-04-18</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.20. @@ -671,10 +671,10 @@ <sect1 id="release-8-2-20"> <title>Release 8.2.20</title> - <note> - <title>Release Date</title> - <simpara>2011-01-31</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-01-31</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.19. @@ -803,10 +803,10 @@ <sect1 id="release-8-2-19"> <title>Release 8.2.19</title> - <note> - <title>Release Date</title> - <simpara>2010-12-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-12-16</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.18. @@ -1047,10 +1047,10 @@ <sect1 id="release-8-2-18"> <title>Release 8.2.18</title> - <note> - <title>Release Date</title> - <simpara>2010-10-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-10-04</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.17. @@ -1333,10 +1333,10 @@ <sect1 id="release-8-2-17"> <title>Release 8.2.17</title> - <note> - <title>Release Date</title> - <simpara>2010-05-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-05-17</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.16. @@ -1442,14 +1442,14 @@ <listitem> <para> - Update pl/perl's <filename>ppport.h</> for modern Perl versions + Update PL/Perl's <filename>ppport.h</> for modern Perl versions (Andrew) </para> </listitem> <listitem> <para> - Fix assorted memory leaks in pl/python (Andreas Freund, Tom) + Fix assorted memory leaks in PL/Python (Andreas Freund, Tom) </para> </listitem> @@ -1487,7 +1487,7 @@ </para> <para> - This behavior has been observed on BSD-derived kernels including OS X. + This behavior has been observed on BSD-derived kernels including macOS. It resulted in an entirely-misleading startup failure complaining that the shared memory request size was too large. </para> @@ -1534,10 +1534,10 @@ <sect1 id="release-8-2-16"> <title>Release 8.2.16</title> - <note> - <title>Release Date</title> - <simpara>2010-03-15</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-03-15</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.15. @@ -1805,10 +1805,10 @@ <sect1 id="release-8-2-15"> <title>Release 8.2.15</title> - <note> - <title>Release Date</title> - <simpara>2009-12-14</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-12-14</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.14. @@ -2049,10 +2049,10 @@ <sect1 id="release-8-2-14"> <title>Release 8.2.14</title> - <note> - <title>Release Date</title> - <simpara>2009-09-09</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-09-09</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.13. @@ -2279,10 +2279,10 @@ <sect1 id="release-8-2-13"> <title>Release 8.2.13</title> - <note> - <title>Release Date</title> - <simpara>2009-03-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-03-16</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.12. @@ -2445,10 +2445,10 @@ <sect1 id="release-8-2-12"> <title>Release 8.2.12</title> - <note> - <title>Release Date</title> - <simpara>2009-02-02</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-02-02</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.11. @@ -2624,10 +2624,10 @@ <sect1 id="release-8-2-11"> <title>Release 8.2.11</title> - <note> - <title>Release Date</title> - <simpara>2008-11-03</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-11-03</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.10. @@ -2808,10 +2808,10 @@ <sect1 id="release-8-2-10"> <title>Release 8.2.10</title> - <note> - <title>Release Date</title> - <simpara>2008-09-22</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-09-22</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.9. @@ -3040,10 +3040,10 @@ <sect1 id="release-8-2-9"> <title>Release 8.2.9</title> - <note> - <title>Release Date</title> - <simpara>2008-06-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-06-12</para> + </formalpara> <para> This release contains one serious and one minor bug fix over 8.2.8. @@ -3107,10 +3107,10 @@ <sect1 id="release-8-2-8"> <title>Release 8.2.8</title> - <note> - <title>Release Date</title> - <simpara>never released</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>never released</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.7. @@ -3302,10 +3302,10 @@ <sect1 id="release-8-2-7"> <title>Release 8.2.7</title> - <note> - <title>Release Date</title> - <simpara>2008-03-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-03-17</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.6. @@ -3571,10 +3571,10 @@ <sect1 id="release-8-2-6"> <title>Release 8.2.6</title> - <note> - <title>Release Date</title> - <simpara>2008-01-07</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-01-07</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.5, @@ -3765,7 +3765,7 @@ <para> While this could theoretically happen anywhere, no standard build of - Perl did things this way ... until <productname>Mac OS X</> 10.5. + Perl did things this way ... until <productname>macOS</> 10.5. </para> </listitem> @@ -3862,10 +3862,10 @@ <sect1 id="release-8-2-5"> <title>Release 8.2.5</title> - <note> - <title>Release Date</title> - <simpara>2007-09-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-09-17</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.4. @@ -4039,10 +4039,10 @@ <sect1 id="release-8-2-4"> <title>Release 8.2.4</title> - <note> - <title>Release Date</title> - <simpara>2007-04-23</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-04-23</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.3, @@ -4183,10 +4183,10 @@ <sect1 id="release-8-2-3"> <title>Release 8.2.3</title> - <note> - <title>Release Date</title> - <simpara>2007-02-07</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-02-07</para> + </formalpara> <para> This release contains two fixes from 8.2.2. @@ -4229,10 +4229,10 @@ <sect1 id="release-8-2-2"> <title>Release 8.2.2</title> - <note> - <title>Release Date</title> - <simpara>2007-02-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-02-05</para> + </formalpara> <para> This release contains a variety of fixes from 8.2.1, including @@ -4387,10 +4387,10 @@ <sect1 id="release-8-2-1"> <title>Release 8.2.1</title> - <note> - <title>Release Date</title> - <simpara>2007-01-08</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-01-08</para> + </formalpara> <para> This release contains a variety of fixes from 8.2. @@ -4522,10 +4522,10 @@ <sect1 id="release-8-2"> <title>Release 8.2</title> - <note> - <title>Release Date</title> - <simpara>2006-12-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-12-05</para> + </formalpara> <sect2> <title>Overview</title> diff --git a/doc/src/sgml/release-8.3.sgml b/doc/src/sgml/release-8.3.sgml index b56edb0102..a82410d057 100644 --- a/doc/src/sgml/release-8.3.sgml +++ b/doc/src/sgml/release-8.3.sgml @@ -4,10 +4,10 @@ <sect1 id="release-8-3-23"> <title>Release 8.3.23</title> - <note> - <title>Release Date</title> - <simpara>2013-02-07</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-02-07</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.22. @@ -173,10 +173,10 @@ <sect1 id="release-8-3-22"> <title>Release 8.3.22</title> - <note> - <title>Release Date</title> - <simpara>2012-12-06</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-12-06</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.21. @@ -469,10 +469,10 @@ <sect1 id="release-8-3-21"> <title>Release 8.3.21</title> - <note> - <title>Release Date</title> - <simpara>2012-09-24</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-09-24</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.20. @@ -579,10 +579,10 @@ <sect1 id="release-8-3-20"> <title>Release 8.3.20</title> - <note> - <title>Release Date</title> - <simpara>2012-08-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-08-17</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.19. @@ -802,10 +802,10 @@ <sect1 id="release-8-3-19"> <title>Release 8.3.19</title> - <note> - <title>Release Date</title> - <simpara>2012-06-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-06-04</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.18. @@ -1031,10 +1031,10 @@ <sect1 id="release-8-3-18"> <title>Release 8.3.18</title> - <note> - <title>Release Date</title> - <simpara>2012-02-27</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-02-27</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.17. @@ -1319,10 +1319,10 @@ <sect1 id="release-8-3-17"> <title>Release 8.3.17</title> - <note> - <title>Release Date</title> - <simpara>2011-12-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-12-05</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.16. @@ -1586,10 +1586,10 @@ <sect1 id="release-8-3-16"> <title>Release 8.3.16</title> - <note> - <title>Release Date</title> - <simpara>2011-09-26</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-09-26</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.15. @@ -1957,10 +1957,10 @@ <sect1 id="release-8-3-15"> <title>Release 8.3.15</title> - <note> - <title>Release Date</title> - <simpara>2011-04-18</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-04-18</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.14. @@ -2120,10 +2120,10 @@ <sect1 id="release-8-3-14"> <title>Release 8.3.14</title> - <note> - <title>Release Date</title> - <simpara>2011-01-31</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-01-31</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.13. @@ -2252,10 +2252,10 @@ <sect1 id="release-8-3-13"> <title>Release 8.3.13</title> - <note> - <title>Release Date</title> - <simpara>2010-12-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-12-16</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.12. @@ -2530,10 +2530,10 @@ <sect1 id="release-8-3-12"> <title>Release 8.3.12</title> - <note> - <title>Release Date</title> - <simpara>2010-10-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-10-04</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.11. @@ -2893,10 +2893,10 @@ <sect1 id="release-8-3-11"> <title>Release 8.3.11</title> - <note> - <title>Release Date</title> - <simpara>2010-05-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-05-17</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.10. @@ -3022,14 +3022,14 @@ <listitem> <para> - Update pl/perl's <filename>ppport.h</> for modern Perl versions + Update PL/Perl's <filename>ppport.h</> for modern Perl versions (Andrew) </para> </listitem> <listitem> <para> - Fix assorted memory leaks in pl/python (Andreas Freund, Tom) + Fix assorted memory leaks in PL/Python (Andreas Freund, Tom) </para> </listitem> @@ -3075,7 +3075,7 @@ </para> <para> - This behavior has been observed on BSD-derived kernels including OS X. + This behavior has been observed on BSD-derived kernels including macOS. It resulted in an entirely-misleading startup failure complaining that the shared memory request size was too large. </para> @@ -3122,10 +3122,10 @@ <sect1 id="release-8-3-10"> <title>Release 8.3.10</title> - <note> - <title>Release Date</title> - <simpara>2010-03-15</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-03-15</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.9. @@ -3449,10 +3449,10 @@ <sect1 id="release-8-3-9"> <title>Release 8.3.9</title> - <note> - <title>Release Date</title> - <simpara>2009-12-14</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-12-14</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.8. @@ -3782,10 +3782,10 @@ <sect1 id="release-8-3-8"> <title>Release 8.3.8</title> - <note> - <title>Release Date</title> - <simpara>2009-09-09</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-09-09</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.7. @@ -4072,10 +4072,10 @@ <sect1 id="release-8-3-7"> <title>Release 8.3.7</title> - <note> - <title>Release Date</title> - <simpara>2009-03-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-03-16</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.6. @@ -4295,10 +4295,10 @@ <sect1 id="release-8-3-6"> <title>Release 8.3.6</title> - <note> - <title>Release Date</title> - <simpara>2009-02-02</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-02-02</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.5. @@ -4589,10 +4589,10 @@ <sect1 id="release-8-3-5"> <title>Release 8.3.5</title> - <note> - <title>Release Date</title> - <simpara>2008-11-03</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-11-03</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.4. @@ -4844,10 +4844,10 @@ <sect1 id="release-8-3-4"> <title>Release 8.3.4</title> - <note> - <title>Release Date</title> - <simpara>2008-09-22</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-09-22</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.3. @@ -5198,10 +5198,10 @@ <sect1 id="release-8-3-3"> <title>Release 8.3.3</title> - <note> - <title>Release Date</title> - <simpara>2008-06-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-06-12</para> + </formalpara> <para> This release contains one serious and one minor bug fix over 8.3.2. @@ -5265,10 +5265,10 @@ <sect1 id="release-8-3-2"> <title>Release 8.3.2</title> - <note> - <title>Release Date</title> - <simpara>never released</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>never released</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.1. @@ -5630,10 +5630,10 @@ <sect1 id="release-8-3-1"> <title>Release 8.3.1</title> - <note> - <title>Release Date</title> - <simpara>2008-03-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-03-17</para> + </formalpara> <para> This release contains a variety of fixes from 8.3.0. @@ -5943,10 +5943,10 @@ <sect1 id="release-8-3"> <title>Release 8.3</title> - <note> - <title>Release Date</title> - <simpara>2008-02-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-02-04</para> + </formalpara> <sect2> <title>Overview</title> @@ -8396,7 +8396,7 @@ current_date < 2017-11-17 <listitem> <para> Use <acronym>SYSV</> semaphores rather than POSIX on Darwin - >= 6.0, i.e., OS X 10.2 and up (Chris Marcellino) + >= 6.0, i.e., macOS 10.2 and up (Chris Marcellino) </para> </listitem> diff --git a/doc/src/sgml/release-8.4.sgml b/doc/src/sgml/release-8.4.sgml index 8b16c9e9d3..16004edb74 100644 --- a/doc/src/sgml/release-8.4.sgml +++ b/doc/src/sgml/release-8.4.sgml @@ -4,10 +4,10 @@ <sect1 id="release-8-4-22"> <title>Release 8.4.22</title> - <note> - <title>Release Date</title> - <simpara>2014-07-24</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2014-07-24</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.21. @@ -240,7 +240,7 @@ <listitem> <para> - Fix linking of <application>libpython</> on OS X (Tom Lane) + Fix linking of <application>libpython</> on macOS (Tom Lane) </para> <para> @@ -323,10 +323,10 @@ <sect1 id="release-8-4-21"> <title>Release 8.4.21</title> - <note> - <title>Release Date</title> - <simpara>2014-03-20</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2014-03-20</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.20. @@ -381,7 +381,7 @@ <para> This prevents scenarios wherein a pathological regular expression - could lock up a server process uninterruptably for a long time. + could lock up a server process uninterruptibly for a long time. </para> </listitem> @@ -442,10 +442,10 @@ <sect1 id="release-8-4-20"> <title>Release 8.4.20</title> - <note> - <title>Release Date</title> - <simpara>2014-02-20</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2014-02-20</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.19. @@ -901,10 +901,10 @@ <sect1 id="release-8-4-19"> <title>Release 8.4.19</title> - <note> - <title>Release Date</title> - <simpara>2013-12-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-12-05</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.18. @@ -1102,10 +1102,10 @@ <sect1 id="release-8-4-18"> <title>Release 8.4.18</title> - <note> - <title>Release Date</title> - <simpara>2013-10-10</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-10-10</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.17. @@ -1302,10 +1302,10 @@ <sect1 id="release-8-4-17"> <title>Release 8.4.17</title> - <note> - <title>Release Date</title> - <simpara>2013-04-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-04-04</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.16. @@ -1531,10 +1531,10 @@ <sect1 id="release-8-4-16"> <title>Release 8.4.16</title> - <note> - <title>Release Date</title> - <simpara>2013-02-07</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-02-07</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.15. @@ -1741,10 +1741,10 @@ <sect1 id="release-8-4-15"> <title>Release 8.4.15</title> - <note> - <title>Release Date</title> - <simpara>2012-12-06</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-12-06</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.14. @@ -2043,10 +2043,10 @@ <sect1 id="release-8-4-14"> <title>Release 8.4.14</title> - <note> - <title>Release Date</title> - <simpara>2012-09-24</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-09-24</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.13. @@ -2159,10 +2159,10 @@ <sect1 id="release-8-4-13"> <title>Release 8.4.13</title> - <note> - <title>Release Date</title> - <simpara>2012-08-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-08-17</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.12. @@ -2393,10 +2393,10 @@ <sect1 id="release-8-4-12"> <title>Release 8.4.12</title> - <note> - <title>Release Date</title> - <simpara>2012-06-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-06-04</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.11. @@ -2678,10 +2678,10 @@ <sect1 id="release-8-4-11"> <title>Release 8.4.11</title> - <note> - <title>Release Date</title> - <simpara>2012-02-27</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-02-27</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.10. @@ -3040,10 +3040,10 @@ <sect1 id="release-8-4-10"> <title>Release 8.4.10</title> - <note> - <title>Release Date</title> - <simpara>2011-12-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-12-05</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.9. @@ -3355,10 +3355,10 @@ <sect1 id="release-8-4-9"> <title>Release 8.4.9</title> - <note> - <title>Release Date</title> - <simpara>2011-09-26</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-09-26</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.8. @@ -3880,10 +3880,10 @@ <sect1 id="release-8-4-8"> <title>Release 8.4.8</title> - <note> - <title>Release Date</title> - <simpara>2011-04-18</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-04-18</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.7. @@ -4125,10 +4125,10 @@ <sect1 id="release-8-4-7"> <title>Release 8.4.7</title> - <note> - <title>Release Date</title> - <simpara>2011-01-31</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-01-31</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.6. @@ -4257,10 +4257,10 @@ <sect1 id="release-8-4-6"> <title>Release 8.4.6</title> - <note> - <title>Release Date</title> - <simpara>2010-12-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-12-16</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.5. @@ -4568,10 +4568,10 @@ <sect1 id="release-8-4-5"> <title>Release 8.4.5</title> - <note> - <title>Release Date</title> - <simpara>2010-10-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-10-04</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.4. @@ -5090,10 +5090,10 @@ <sect1 id="release-8-4-4"> <title>Release 8.4.4</title> - <note> - <title>Release Date</title> - <simpara>2010-05-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-05-17</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.3. @@ -5260,21 +5260,21 @@ <listitem> <para> - Fix pl/pgsql's <literal>CASE</> statement to not fail when the + Fix PL/pgSQL's <literal>CASE</> statement to not fail when the case expression is a query that returns no rows (Tom) </para> </listitem> <listitem> <para> - Update pl/perl's <filename>ppport.h</> for modern Perl versions + Update PL/Perl's <filename>ppport.h</> for modern Perl versions (Andrew) </para> </listitem> <listitem> <para> - Fix assorted memory leaks in pl/python (Andreas Freund, Tom) + Fix assorted memory leaks in PL/Python (Andreas Freund, Tom) </para> </listitem> @@ -5334,7 +5334,7 @@ </para> <para> - This behavior has been observed on BSD-derived kernels including OS X. + This behavior has been observed on BSD-derived kernels including macOS. It resulted in an entirely-misleading startup failure complaining that the shared memory request size was too large. </para> @@ -5381,10 +5381,10 @@ <sect1 id="release-8-4-3"> <title>Release 8.4.3</title> - <note> - <title>Release Date</title> - <simpara>2010-03-15</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-03-15</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.2. @@ -5848,10 +5848,10 @@ <sect1 id="release-8-4-2"> <title>Release 8.4.2</title> - <note> - <title>Release Date</title> - <simpara>2009-12-14</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-12-14</para> + </formalpara> <para> This release contains a variety of fixes from 8.4.1. @@ -6379,10 +6379,10 @@ WITH w AS (SELECT * FROM foo) SELECT * FROM w, bar ... FOR UPDATE <sect1 id="release-8-4-1"> <title>Release 8.4.1</title> - <note> - <title>Release Date</title> - <simpara>2009-09-09</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-09-09</para> + </formalpara> <para> This release contains a variety of fixes from 8.4. @@ -6678,10 +6678,10 @@ WITH w AS (SELECT * FROM foo) SELECT * FROM w, bar ... FOR UPDATE <sect1 id="release-8-4"> <title>Release 8.4</title> - <note> - <title>Release Date</title> - <simpara>2009-07-01</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2009-07-01</para> + </formalpara> <sect2> <title>Overview</title> @@ -9764,7 +9764,7 @@ WITH w AS (SELECT * FROM foo) SELECT * FROM w, bar ... FOR UPDATE <listitem> <para> - Enable <application>DTrace</> support on <application>Mac OS X + Enable <application>DTrace</> support on <application>macOS Leopard</> and other non-Solaris platforms (Robert Lor) </para> </listitem> diff --git a/doc/src/sgml/release-9.0.sgml b/doc/src/sgml/release-9.0.sgml index 61dce9fd78..e7d2ffddaf 100644 --- a/doc/src/sgml/release-9.0.sgml +++ b/doc/src/sgml/release-9.0.sgml @@ -4,10 +4,10 @@ <sect1 id="release-9-0-23"> <title>Release 9.0.23</title> - <note> - <title>Release Date</title> - <simpara>2015-10-08</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-10-08</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.22. @@ -501,10 +501,10 @@ <sect1 id="release-9-0-22"> <title>Release 9.0.22</title> - <note> - <title>Release Date</title> - <simpara>2015-06-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-06-12</para> + </formalpara> <para> This release contains a small number of fixes from 9.0.21. @@ -575,10 +575,10 @@ <sect1 id="release-9-0-21"> <title>Release 9.0.21</title> - <note> - <title>Release Date</title> - <simpara>2015-06-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-06-04</para> + </formalpara> <para> This release contains a small number of fixes from 9.0.20. @@ -669,10 +669,10 @@ <sect1 id="release-9-0-20"> <title>Release 9.0.20</title> - <note> - <title>Release Date</title> - <simpara>2015-05-22</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-05-22</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.19. @@ -1113,10 +1113,10 @@ <sect1 id="release-9-0-19"> <title>Release 9.0.19</title> - <note> - <title>Release Date</title> - <simpara>2015-02-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-02-05</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.18. @@ -1541,7 +1541,7 @@ <listitem> <para> - Warn if OS X's <function>setlocale()</> starts an unwanted extra + Warn if macOS's <function>setlocale()</> starts an unwanted extra thread inside the postmaster (Noah Misch) </para> </listitem> @@ -1839,10 +1839,10 @@ <sect1 id="release-9-0-18"> <title>Release 9.0.18</title> - <note> - <title>Release Date</title> - <simpara>2014-07-24</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2014-07-24</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.17. @@ -2093,7 +2093,7 @@ <listitem> <para> - Fix linking of <application>libpython</> on OS X (Tom Lane) + Fix linking of <application>libpython</> on macOS (Tom Lane) </para> <para> @@ -2185,10 +2185,10 @@ <sect1 id="release-9-0-17"> <title>Release 9.0.17</title> - <note> - <title>Release Date</title> - <simpara>2014-03-20</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2014-03-20</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.16. @@ -2250,7 +2250,7 @@ <para> This prevents scenarios wherein a pathological regular expression - could lock up a server process uninterruptably for a long time. + could lock up a server process uninterruptibly for a long time. </para> </listitem> @@ -2338,10 +2338,10 @@ <sect1 id="release-9-0-16"> <title>Release 9.0.16</title> - <note> - <title>Release Date</title> - <simpara>2014-02-20</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2014-02-20</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.15. @@ -2839,10 +2839,10 @@ <sect1 id="release-9-0-15"> <title>Release 9.0.15</title> - <note> - <title>Release Date</title> - <simpara>2013-12-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-12-05</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.14. @@ -3077,10 +3077,10 @@ <sect1 id="release-9-0-14"> <title>Release 9.0.14</title> - <note> - <title>Release Date</title> - <simpara>2013-10-10</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-10-10</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.13. @@ -3343,10 +3343,10 @@ <sect1 id="release-9-0-13"> <title>Release 9.0.13</title> - <note> - <title>Release Date</title> - <simpara>2013-04-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-04-04</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.12. @@ -3640,10 +3640,10 @@ <sect1 id="release-9-0-12"> <title>Release 9.0.12</title> - <note> - <title>Release Date</title> - <simpara>2013-02-07</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-02-07</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.11. @@ -3902,10 +3902,10 @@ <sect1 id="release-9-0-11"> <title>Release 9.0.11</title> - <note> - <title>Release Date</title> - <simpara>2012-12-06</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-12-06</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.10. @@ -4280,10 +4280,10 @@ <sect1 id="release-9-0-10"> <title>Release 9.0.10</title> - <note> - <title>Release Date</title> - <simpara>2012-09-24</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-09-24</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.9. @@ -4422,10 +4422,10 @@ <sect1 id="release-9-0-9"> <title>Release 9.0.9</title> - <note> - <title>Release Date</title> - <simpara>2012-08-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-08-17</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.8. @@ -4728,10 +4728,10 @@ <sect1 id="release-9-0-8"> <title>Release 9.0.8</title> - <note> - <title>Release Date</title> - <simpara>2012-06-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-06-04</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.7. @@ -5048,10 +5048,10 @@ <sect1 id="release-9-0-7"> <title>Release 9.0.7</title> - <note> - <title>Release Date</title> - <simpara>2012-02-27</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-02-27</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.6. @@ -5564,10 +5564,10 @@ <sect1 id="release-9-0-6"> <title>Release 9.0.6</title> - <note> - <title>Release Date</title> - <simpara>2011-12-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-12-05</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.5. @@ -5895,7 +5895,7 @@ <listitem> <para> - Fix incorrect quoting of log file name in Mac OS X start script + Fix incorrect quoting of log file name in macOS start script (Sidar Lopez) </para> </listitem> @@ -5948,10 +5948,10 @@ <sect1 id="release-9-0-5"> <title>Release 9.0.5</title> - <note> - <title>Release Date</title> - <simpara>2011-09-26</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-09-26</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.4. @@ -6598,10 +6598,10 @@ <sect1 id="release-9-0-4"> <title>Release 9.0.4</title> - <note> - <title>Release Date</title> - <simpara>2011-04-18</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-04-18</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.3. @@ -6939,10 +6939,10 @@ <sect1 id="release-9-0-3"> <title>Release 9.0.3</title> - <note> - <title>Release Date</title> - <simpara>2011-01-31</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-01-31</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.2. @@ -7115,10 +7115,10 @@ <sect1 id="release-9-0-2"> <title>Release 9.0.2</title> - <note> - <title>Release Date</title> - <simpara>2010-12-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-12-16</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.1. @@ -7562,10 +7562,10 @@ <sect1 id="release-9-0-1"> <title>Release 9.0.1</title> - <note> - <title>Release Date</title> - <simpara>2010-10-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-10-04</para> + </formalpara> <para> This release contains a variety of fixes from 9.0.0. @@ -7704,10 +7704,10 @@ <sect1 id="release-9-0"> <title>Release 9.0</title> - <note> - <title>Release Date</title> - <simpara>2010-09-20</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2010-09-20</para> + </formalpara> <sect2> <title>Overview</title> @@ -10745,7 +10745,7 @@ if TG_OP = 'INSERT' and NEW.col1 = ... then </para> <para> - Bonjour support now requires <productname>OS X</> 10.3 or later. + Bonjour support now requires <productname>macOS</> 10.3 or later. The older API has been deprecated by Apple. </para> </listitem> diff --git a/doc/src/sgml/release-9.1.sgml b/doc/src/sgml/release-9.1.sgml index a66ca0d5b3..0454f849d4 100644 --- a/doc/src/sgml/release-9.1.sgml +++ b/doc/src/sgml/release-9.1.sgml @@ -1,13 +1,223 @@ <!-- doc/src/sgml/release-9.1.sgml --> <!-- See header comment in release.sgml about typical markup --> + <sect1 id="release-9-1-24"> + <title>Release 9.1.24</title> + + <formalpara> + <title>Release date:</title> + <para>2016-10-27</para> + </formalpara> + + <para> + This release contains a variety of fixes from 9.1.23. + For information about new features in the 9.1 major release, see + <xref linkend="release-9-1">. + </para> + + <para> + This is expected to be the last <productname>PostgreSQL</> release + in the 9.1.X series. Users are encouraged to update to a newer + release branch soon. + </para> + + <sect2> + <title>Migration to Version 9.1.24</title> + + <para> + A dump/restore is not required for those running 9.1.X. + </para> + + <para> + However, if you are upgrading from a version earlier than 9.1.16, + see <xref linkend="release-9-1-16">. + </para> + + </sect2> + + <sect2> + <title>Changes</title> + + <itemizedlist> + + <listitem> + <para> + Fix EvalPlanQual rechecks involving CTE scans (Tom Lane) + </para> + + <para> + The recheck would always see the CTE as returning no rows, typically + leading to failure to update rows that were recently updated. + </para> + </listitem> + + <listitem> + <para> + Fix improper repetition of previous results from hashed aggregation in + a subquery (Andrew Gierth) + </para> + + <para> + The test to see if we can reuse a previously-computed hash table of + the aggregate state values neglected the possibility of an outer query + reference appearing in an aggregate argument expression. A change in + the value of such a reference should lead to recalculating the hash + table, but did not. + </para> + </listitem> + + <listitem> + <para> + Fix timeout length when <command>VACUUM</> is waiting for exclusive + table lock so that it can truncate the table (Simon Riggs) + </para> + + <para> + The timeout was meant to be 50 milliseconds, but it was actually only + 50 microseconds, causing <command>VACUUM</> to give up on truncation + much more easily than intended. Set it to the intended value. + </para> + </listitem> + + <listitem> + <para> + Remove artificial restrictions on the values accepted + by <function>numeric_in()</> and <function>numeric_recv()</> + (Tom Lane) + </para> + + <para> + We allow numeric values up to the limit of the storage format (more + than <literal>1e100000</>), so it seems fairly pointless + that <function>numeric_in()</> rejected scientific-notation exponents + above 1000. Likewise, it was silly for <function>numeric_recv()</> to + reject more than 1000 digits in an input value. + </para> + </listitem> + + <listitem> + <para> + Avoid very-low-probability data corruption due to testing tuple + visibility without holding buffer lock (Thomas Munro, Peter Geoghegan, + Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix file descriptor leakage when truncating a temporary relation of + more than 1GB (Andres Freund) + </para> + </listitem> + + <listitem> + <para> + Disallow starting a standalone backend with <literal>standby_mode</> + turned on (Michael Paquier) + </para> + + <para> + This can't do anything useful, since there will be no WAL receiver + process to fetch more WAL data; and it could result in misbehavior + in code that wasn't designed with this situation in mind. + </para> + </listitem> + + <listitem> + <para> + Don't try to share SSL contexts across multiple connections + in <application>libpq</> (Heikki Linnakangas) + </para> + + <para> + This led to assorted corner-case bugs, particularly when trying to use + different SSL parameters for different connections. + </para> + </listitem> + + <listitem> + <para> + Avoid corner-case memory leak in <application>libpq</> (Tom Lane) + </para> + + <para> + The reported problem involved leaking an error report + during <function>PQreset()</>, but there might be related cases. + </para> + </listitem> + + <listitem> + <para> + Make <application>ecpg</>'s <option>--help</> and <option>--version</> + options work consistently with our other executables (Haribabu Kommi) + </para> + </listitem> + + <listitem> + <para> + Fix <filename>contrib/intarray/bench/bench.pl</> to print the results + of the <command>EXPLAIN</> it does when given the <option>-e</> option + (Daniel Gustafsson) + </para> + </listitem> + + <listitem> + <para> + Prevent failure of obsolete dynamic time zone abbreviations (Tom Lane) + </para> + + <para> + If a dynamic time zone abbreviation does not match any entry in the + referenced time zone, treat it as equivalent to the time zone name. + This avoids unexpected failures when IANA removes abbreviations from + their time zone database, as they did in <application>tzdata</> + release 2016f and seem likely to do again in the future. The + consequences were not limited to not recognizing the individual + abbreviation; any mismatch caused + the <structname>pg_timezone_abbrevs</> view to fail altogether. + </para> + </listitem> + + <listitem> + <para> + Update time zone data files to <application>tzdata</> release 2016h + for DST law changes in Palestine and Turkey, plus historical + corrections for Turkey and some regions of Russia. + Switch to numeric abbreviations for some time zones in Antarctica, + the former Soviet Union, and Sri Lanka. + </para> + + <para> + The IANA time zone database previously provided textual abbreviations + for all time zones, sometimes making up abbreviations that have little + or no currency among the local population. They are in process of + reversing that policy in favor of using numeric UTC offsets in zones + where there is no evidence of real-world use of an English + abbreviation. At least for the time being, <productname>PostgreSQL</> + will continue to accept such removed abbreviations for timestamp input. + But they will not be shown in the <structname>pg_timezone_names</> + view nor used for output. + </para> + + <para> + In this update, <literal>AMT</> is no longer shown as being in use to + mean Armenia Time. Therefore, we have changed the <literal>Default</> + abbreviation set to interpret it as Amazon Time, thus UTC-4 not UTC+4. + </para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + <sect1 id="release-9-1-23"> <title>Release 9.1.23</title> - <note> - <title>Release Date</title> - <simpara>2016-08-11</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-08-11</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.22. @@ -346,10 +556,10 @@ Branch: REL9_1_STABLE [354b3a3ac] 2016-06-19 14:01:17 -0400 <sect1 id="release-9-1-22"> <title>Release 9.1.22</title> - <note> - <title>Release Date</title> - <simpara>2016-05-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-05-12</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.21. @@ -511,10 +721,10 @@ Branch: REL9_1_STABLE [354b3a3ac] 2016-06-19 14:01:17 -0400 <sect1 id="release-9-1-21"> <title>Release 9.1.21</title> - <note> - <title>Release Date</title> - <simpara>2016-03-31</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-03-31</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.20. @@ -599,7 +809,7 @@ Branch: REL9_1_STABLE [354b3a3ac] 2016-06-19 14:01:17 -0400 <para> This dodges a portability problem on FreeBSD-derived platforms - (including OS X). + (including macOS). </para> </listitem> @@ -717,10 +927,10 @@ Branch: REL9_1_STABLE [354b3a3ac] 2016-06-19 14:01:17 -0400 <sect1 id="release-9-1-20"> <title>Release 9.1.20</title> - <note> - <title>Release Date</title> - <simpara>2016-02-11</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-02-11</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.19. @@ -1230,10 +1440,10 @@ Branch: REL9_1_STABLE [354b3a3ac] 2016-06-19 14:01:17 -0400 <sect1 id="release-9-1-19"> <title>Release 9.1.19</title> - <note> - <title>Release Date</title> - <simpara>2015-10-08</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-10-08</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.18. @@ -1791,10 +2001,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-18"> <title>Release 9.1.18</title> - <note> - <title>Release Date</title> - <simpara>2015-06-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-06-12</para> + </formalpara> <para> This release contains a small number of fixes from 9.1.17. @@ -1859,10 +2069,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-17"> <title>Release 9.1.17</title> - <note> - <title>Release Date</title> - <simpara>2015-06-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-06-04</para> + </formalpara> <para> This release contains a small number of fixes from 9.1.16. @@ -1947,10 +2157,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-16"> <title>Release 9.1.16</title> - <note> - <title>Release Date</title> - <simpara>2015-05-22</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-05-22</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.15. @@ -2473,10 +2683,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-15"> <title>Release 9.1.15</title> - <note> - <title>Release Date</title> - <simpara>2015-02-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-02-05</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.14. @@ -2937,7 +3147,7 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <listitem> <para> - Warn if OS X's <function>setlocale()</> starts an unwanted extra + Warn if macOS's <function>setlocale()</> starts an unwanted extra thread inside the postmaster (Noah Misch) </para> </listitem> @@ -3283,10 +3493,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-14"> <title>Release 9.1.14</title> - <note> - <title>Release Date</title> - <simpara>2014-07-24</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2014-07-24</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.13. @@ -3574,7 +3784,7 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <listitem> <para> - Fix linking of <application>libpython</> on OS X (Tom Lane) + Fix linking of <application>libpython</> on macOS (Tom Lane) </para> <para> @@ -3666,10 +3876,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-13"> <title>Release 9.1.13</title> - <note> - <title>Release Date</title> - <simpara>2014-03-20</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2014-03-20</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.12. @@ -3731,7 +3941,7 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <para> This prevents scenarios wherein a pathological regular expression - could lock up a server process uninterruptably for a long time. + could lock up a server process uninterruptibly for a long time. </para> </listitem> @@ -3833,10 +4043,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-12"> <title>Release 9.1.12</title> - <note> - <title>Release Date</title> - <simpara>2014-02-20</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2014-02-20</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.11. @@ -4383,10 +4593,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-11"> <title>Release 9.1.11</title> - <note> - <title>Release Date</title> - <simpara>2013-12-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-12-05</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.10. @@ -4640,10 +4850,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-10"> <title>Release 9.1.10</title> - <note> - <title>Release Date</title> - <simpara>2013-10-10</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-10-10</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.9. @@ -4975,10 +5185,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-9"> <title>Release 9.1.9</title> - <note> - <title>Release Date</title> - <simpara>2013-04-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-04-04</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.8. @@ -5309,10 +5519,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-8"> <title>Release 9.1.8</title> - <note> - <title>Release Date</title> - <simpara>2013-02-07</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-02-07</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.7. @@ -5631,10 +5841,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-7"> <title>Release 9.1.7</title> - <note> - <title>Release Date</title> - <simpara>2012-12-06</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-12-06</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.6. @@ -6094,10 +6304,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-6"> <title>Release 9.1.6</title> - <note> - <title>Release Date</title> - <simpara>2012-09-24</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-09-24</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.5. @@ -6346,10 +6556,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-5"> <title>Release 9.1.5</title> - <note> - <title>Release Date</title> - <simpara>2012-08-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-08-17</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.4. @@ -6733,10 +6943,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-4"> <title>Release 9.1.4</title> - <note> - <title>Release Date</title> - <simpara>2012-06-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-06-04</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.3. @@ -7223,10 +7433,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-3"> <title>Release 9.1.3</title> - <note> - <title>Release Date</title> - <simpara>2012-02-27</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-02-27</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.2. @@ -7860,10 +8070,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-2"> <title>Release 9.1.2</title> - <note> - <title>Release Date</title> - <simpara>2011-12-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-12-05</para> + </formalpara> <para> This release contains a variety of fixes from 9.1.1. @@ -8443,7 +8653,7 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <listitem> <para> - Fix incorrect quoting of log file name in Mac OS X start script + Fix incorrect quoting of log file name in macOS start script (Sidar Lopez) </para> </listitem> @@ -8507,10 +8717,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1-1"> <title>Release 9.1.1</title> - <note> - <title>Release Date</title> - <simpara>2011-09-26</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-09-26</para> + </formalpara> <para> This release contains a small number of fixes from 9.1.0. @@ -8575,10 +8785,10 @@ Branch: REL9_0_STABLE [9d6af7367] 2015-08-15 11:02:34 -0400 <sect1 id="release-9-1"> <title>Release 9.1</title> - <note> - <title>Release Date</title> - <simpara>2011-09-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2011-09-12</para> + </formalpara> <sect2> <title>Overview</title> @@ -10650,9 +10860,7 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10; <listitem> <para> - Mark <link - linkend="APP-CREATELANG"><application>createlang</></link> - and <link linkend="APP-DROPLANG"><application>droplang</></link> + Mark <application>createlang</> and <application>droplang</> as deprecated now that they just invoke extension commands (Tom Lane) </para> diff --git a/doc/src/sgml/release-9.2.sgml b/doc/src/sgml/release-9.2.sgml index c801f98c3f..1f1cc12b61 100644 --- a/doc/src/sgml/release-9.2.sgml +++ b/doc/src/sgml/release-9.2.sgml @@ -1,13 +1,1139 @@ <!-- doc/src/sgml/release-9.2.sgml --> <!-- See header comment in release.sgml about typical markup --> + <sect1 id="release-9-2-21"> + <title>Release 9.2.21</title> + + <formalpara> + <title>Release date:</title> + <para>2017-05-11</para> + </formalpara> + + <para> + This release contains a variety of fixes from 9.2.20. + For information about new features in the 9.2 major release, see + <xref linkend="release-9-2">. + </para> + + <para> + The <productname>PostgreSQL</> community will stop releasing updates + for the 9.2.X release series in September 2017. + Users are encouraged to update to a newer release branch soon. + </para> + + <sect2> + <title>Migration to Version 9.2.21</title> + + <para> + A dump/restore is not required for those running 9.2.X. + </para> + + <para> + However, if you use foreign data servers that make use of user + passwords for authentication, see the first changelog entry below. + </para> + + <para> + Also, if you are upgrading from a version earlier than 9.2.20, + see <xref linkend="release-9-2-20">. + </para> + + </sect2> + + <sect2> + <title>Changes</title> + + <itemizedlist> + + <listitem> + <para> + Restrict visibility + of <structname>pg_user_mappings</>.<structfield>umoptions</>, to + protect passwords stored as user mapping options + (Michael Paquier, Feike Steenbergen) + </para> + + <para> + The previous coding allowed the owner of a foreign server object, + or anyone he has granted server <literal>USAGE</> permission to, + to see the options for all user mappings associated with that server. + This might well include passwords for other users. + Adjust the view definition to match the behavior of + <structname>information_schema.user_mapping_options</>, namely that + these options are visible to the user being mapped, or if the mapping + is for <literal>PUBLIC</literal> and the current user is the server + owner, or if the current user is a superuser. + (CVE-2017-7486) + </para> + + <para> + By itself, this patch will only fix the behavior in newly initdb'd + databases. If you wish to apply this change in an existing database, + you will need to do the following: + </para> + + <procedure> + <step> + <para> + Restart the postmaster after adding <literal>allow_system_table_mods + = true</> to <filename>postgresql.conf</>. (In versions + supporting <command>ALTER SYSTEM</>, you can use that to make the + configuration change, but you'll still need a restart.) + </para> + </step> + + <step> + <para> + In <emphasis>each</> database of the cluster, + run the following commands as superuser: +<programlisting> +SET search_path = pg_catalog; +CREATE OR REPLACE VIEW pg_user_mappings AS + SELECT + U.oid AS umid, + S.oid AS srvid, + S.srvname AS srvname, + U.umuser AS umuser, + CASE WHEN U.umuser = 0 THEN + 'public' + ELSE + A.rolname + END AS usename, + CASE WHEN (U.umuser <> 0 AND A.rolname = current_user) + OR (U.umuser = 0 AND pg_has_role(S.srvowner, 'USAGE')) + OR (SELECT rolsuper FROM pg_authid WHERE rolname = current_user) + THEN U.umoptions + ELSE NULL END AS umoptions + FROM pg_user_mapping U + LEFT JOIN pg_authid A ON (A.oid = U.umuser) JOIN + pg_foreign_server S ON (U.umserver = S.oid); +</programlisting> + </para> + </step> + + <step> + <para> + Do not forget to include the <literal>template0</> + and <literal>template1</> databases, or the vulnerability will still + exist in databases you create later. To fix <literal>template0</>, + you'll need to temporarily make it accept connections. + In <productname>PostgreSQL</> 9.5 and later, you can use +<programlisting> +ALTER DATABASE template0 WITH ALLOW_CONNECTIONS true; +</programlisting> + and then after fixing <literal>template0</>, undo that with +<programlisting> +ALTER DATABASE template0 WITH ALLOW_CONNECTIONS false; +</programlisting> + In prior versions, instead use +<programlisting> +UPDATE pg_database SET datallowconn = true WHERE datname = 'template0'; +UPDATE pg_database SET datallowconn = false WHERE datname = 'template0'; +</programlisting> + </para> + </step> + + <step> + <para> + Finally, remove the <literal>allow_system_table_mods</> configuration + setting, and again restart the postmaster. + </para> + </step> + </procedure> + </listitem> + + <listitem> + <para> + Prevent exposure of statistical information via leaky operators + (Peter Eisentraut) + </para> + + <para> + Some selectivity estimation functions in the planner will apply + user-defined operators to values obtained + from <structname>pg_statistic</>, such as most common values and + histogram entries. This occurs before table permissions are checked, + so a nefarious user could exploit the behavior to obtain these values + for table columns he does not have permission to read. To fix, + fall back to a default estimate if the operator's implementation + function is not certified leak-proof and the calling user does not have + permission to read the table column whose statistics are needed. + At least one of these criteria is satisfied in most cases in practice. + (CVE-2017-7484) + </para> + </listitem> + + <listitem> + <para> + Fix possible corruption of <quote>init forks</> of unlogged indexes + (Robert Haas, Michael Paquier) + </para> + + <para> + This could result in an unlogged index being set to an invalid state + after a crash and restart. Such a problem would persist until the + index was dropped and rebuilt. + </para> + </listitem> + + <listitem> + <para> + Fix incorrect reconstruction of <structname>pg_subtrans</> entries + when a standby server replays a prepared but uncommitted two-phase + transaction (Tom Lane) + </para> + + <para> + In most cases this turned out to have no visible ill effects, but in + corner cases it could result in circular references + in <structname>pg_subtrans</>, potentially causing infinite loops + in queries that examine rows modified by the two-phase transaction. + </para> + </listitem> + + <listitem> + <para> + Ensure parsing of queries in extension scripts sees the results of + immediately-preceding DDL (Julien Rouhaud, Tom Lane) + </para> + + <para> + Due to lack of a cache flush step between commands in an extension + script file, non-utility queries might not see the effects of an + immediately preceding catalog change, such as <command>ALTER TABLE + ... RENAME</>. + </para> + </listitem> + + <listitem> + <para> + Skip tablespace privilege checks when <command>ALTER TABLE ... ALTER + COLUMN TYPE</> rebuilds an existing index (Noah Misch) + </para> + + <para> + The command failed if the calling user did not currently have + <literal>CREATE</> privilege for the tablespace containing the index. + That behavior seems unhelpful, so skip the check, allowing the + index to be rebuilt where it is. + </para> + </listitem> + + <listitem> + <para> + Fix <command>ALTER TABLE ... VALIDATE CONSTRAINT</> to not recurse + to child tables when the constraint is marked <literal>NO INHERIT</> + (Amit Langote) + </para> + + <para> + This fix prevents unwanted <quote>constraint does not exist</> failures + when no matching constraint is present in the child tables. + </para> + </listitem> + + <listitem> + <para> + Fix <command>VACUUM</> to account properly for pages that could not + be scanned due to conflicting page pins (Andrew Gierth) + </para> + + <para> + This tended to lead to underestimation of the number of tuples in + the table. In the worst case of a small heavily-contended + table, <command>VACUUM</> could incorrectly report that the table + contained no tuples, leading to very bad planning choices. + </para> + </listitem> + + <listitem> + <para> + Ensure that bulk-tuple-transfer loops within a hash join are + interruptible by query cancel requests (Tom Lane, Thomas Munro) + </para> + </listitem> + + <listitem> + <para> + Fix <function>cursor_to_xml()</> to produce valid output + with <replaceable>tableforest</> = false + (Thomas Munro, Peter Eisentraut) + </para> + + <para> + Previously it failed to produce a wrapping <literal><table></> + element. + </para> + </listitem> + + <listitem> + <para> + Improve performance of <structname>pg_timezone_names</> view + (Tom Lane, David Rowley) + </para> + </listitem> + + <listitem> + <para> + Fix sloppy handling of corner-case errors from <function>lseek()</> + and <function>close()</> (Tom Lane) + </para> + + <para> + Neither of these system calls are likely to fail in typical situations, + but if they did, <filename>fd.c</> could get quite confused. + </para> + </listitem> + + <listitem> + <para> + Fix incorrect check for whether postmaster is running as a Windows + service (Michael Paquier) + </para> + + <para> + This could result in attempting to write to the event log when that + isn't accessible, so that no logging happens at all. + </para> + </listitem> + + <listitem> + <para> + Fix <application>ecpg</> to support <command>COMMIT PREPARED</> + and <command>ROLLBACK PREPARED</> (Masahiko Sawada) + </para> + </listitem> + + <listitem> + <para> + Fix a double-free error when processing dollar-quoted string literals + in <application>ecpg</> (Michael Meskes) + </para> + </listitem> + + <listitem> + <para> + In <application>pg_dump</>, fix incorrect schema and owner marking for + comments and security labels of some types of database objects + (Giuseppe Broccolo, Tom Lane) + </para> + + <para> + In simple cases this caused no ill effects; but for example, a + schema-selective restore might omit comments it should include, because + they were not marked as belonging to the schema of their associated + object. + </para> + </listitem> + + <listitem> + <para> + Avoid emitting an invalid list file in <literal>pg_restore -l</> + when SQL object names contain newlines (Tom Lane) + </para> + + <para> + Replace newlines by spaces, which is sufficient to make the output + valid for <literal>pg_restore -L</>'s purposes. + </para> + </listitem> + + <listitem> + <para> + Fix <application>pg_upgrade</> to transfer comments and security labels + attached to <quote>large objects</> (blobs) (Stephen Frost) + </para> + + <para> + Previously, blobs were correctly transferred to the new database, but + any comments or security labels attached to them were lost. + </para> + </listitem> + + <listitem> + <para> + Improve error handling + in <filename>contrib/adminpack</>'s <function>pg_file_write()</> + function (Noah Misch) + </para> + + <para> + Notably, it failed to detect errors reported + by <function>fclose()</>. + </para> + </listitem> + + <listitem> + <para> + In <filename>contrib/dblink</>, avoid leaking the previous unnamed + connection when establishing a new unnamed connection (Joe Conway) + </para> + </listitem> + + <listitem> + <para> + Support OpenSSL 1.1.0 (Heikki Linnakangas, Andreas Karlsson, Tom Lane) + </para> + + <para> + This is a back-patch of work previously done in newer branches; + it's needed since many platforms are adopting newer OpenSSL versions. + </para> + </listitem> + + <listitem> + <para> + Support Tcl 8.6 in MSVC builds (Álvaro Herrera) + </para> + </listitem> + + <listitem> + <para> + Sync our copy of the timezone library with IANA release tzcode2017b + (Tom Lane) + </para> + + <para> + This fixes a bug affecting some DST transitions in January 2038. + </para> + </listitem> + + <listitem> + <para> + Update time zone data files to <application>tzdata</> release 2017b + for DST law changes in Chile, Haiti, and Mongolia, plus historical + corrections for Ecuador, Kazakhstan, Liberia, and Spain. + Switch to numeric abbreviations for numerous time zones in South + America, the Pacific and Indian oceans, and some Asian and Middle + Eastern countries. + </para> + + <para> + The IANA time zone database previously provided textual abbreviations + for all time zones, sometimes making up abbreviations that have little + or no currency among the local population. They are in process of + reversing that policy in favor of using numeric UTC offsets in zones + where there is no evidence of real-world use of an English + abbreviation. At least for the time being, <productname>PostgreSQL</> + will continue to accept such removed abbreviations for timestamp input. + But they will not be shown in the <structname>pg_timezone_names</> + view nor used for output. + </para> + </listitem> + + <listitem> + <para> + Use correct daylight-savings rules for POSIX-style time zone names + in MSVC builds (David Rowley) + </para> + + <para> + The Microsoft MSVC build scripts neglected to install + the <filename>posixrules</> file in the timezone directory tree. + This resulted in the timezone code falling back to its built-in + rule about what DST behavior to assume for a POSIX-style time zone + name. For historical reasons that still corresponds to the DST rules + the USA was using before 2007 (i.e., change on first Sunday in April + and last Sunday in October). With this fix, a POSIX-style zone name + will use the current and historical DST transition dates of + the <literal>US/Eastern</> zone. If you don't want that, remove + the <filename>posixrules</> file, or replace it with a copy of some + other zone file (see <xref linkend="datatype-timezones">). Note that + due to caching, you may need to restart the server to get such changes + to take effect. + </para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + + <sect1 id="release-9-2-20"> + <title>Release 9.2.20</title> + + <formalpara> + <title>Release date:</title> + <para>2017-02-09</para> + </formalpara> + + <para> + This release contains a variety of fixes from 9.2.19. + For information about new features in the 9.2 major release, see + <xref linkend="release-9-2">. + </para> + + <sect2> + <title>Migration to Version 9.2.20</title> + + <para> + A dump/restore is not required for those running 9.2.X. + </para> + + <para> + However, if your installation has been affected by the bug described in + the first changelog entry below, then after updating you may need + to take action to repair corrupted indexes. + </para> + + <para> + Also, if you are upgrading from a version earlier than 9.2.11, + see <xref linkend="release-9-2-11">. + </para> + + </sect2> + + <sect2> + <title>Changes</title> + + <itemizedlist> + + <listitem> + <para> + Fix a race condition that could cause indexes built + with <command>CREATE INDEX CONCURRENTLY</> to be corrupt + (Pavan Deolasee, Tom Lane) + </para> + + <para> + If <command>CREATE INDEX CONCURRENTLY</> was used to build an index + that depends on a column not previously indexed, then rows + updated by transactions that ran concurrently with + the <command>CREATE INDEX</> command could have received incorrect + index entries. If you suspect this may have happened, the most + reliable solution is to rebuild affected indexes after installing + this update. + </para> + </listitem> + + <listitem> + <para> + Unconditionally WAL-log creation of the <quote>init fork</> for an + unlogged table (Michael Paquier) + </para> + + <para> + Previously, this was skipped when <xref linkend="guc-wal-level"> + = <literal>minimal</>, but actually it's necessary even in that case + to ensure that the unlogged table is properly reset to empty after a + crash. + </para> + </listitem> + + <listitem> +<!-- +Author: Fujii Masao <[email protected]> +Branch: REL9_2_STABLE [38bec1805] 2017-01-25 07:02:25 +0900 +--> + <para> + Fix WAL page header validation when re-reading segments (Takayuki + Tsunakawa, Amit Kapila) + </para> + + <para> + In corner cases, a spurious <quote>out-of-sequence TLI</> error + could be reported during recovery. + </para> + </listitem> + + <listitem> + <para> + If the stats collector dies during hot standby, restart it (Takayuki + Tsunakawa) + </para> + </listitem> + + <listitem> + <para> + Check for interrupts while hot standby is waiting for a conflicting + query (Simon Riggs) + </para> + </listitem> + + <listitem> + <para> + Avoid constantly respawning the autovacuum launcher in a corner case + (Amit Khandekar) + </para> + + <para> + This fix avoids problems when autovacuum is nominally off and there + are some tables that require freezing, but all such tables are + already being processed by autovacuum workers. + </para> + </listitem> + + <listitem> + <para> + Fix check for when an extension member object can be dropped (Tom Lane) + </para> + + <para> + Extension upgrade scripts should be able to drop member objects, + but this was disallowed for serial-column sequences, and possibly + other cases. + </para> + </listitem> + + <listitem> + <para> + Make sure <command>ALTER TABLE</> preserves index tablespace + assignments when rebuilding indexes (Tom Lane, Michael Paquier) + </para> + + <para> + Previously, non-default settings + of <xref linkend="guc-default-tablespace"> could result in broken + indexes. + </para> + </listitem> + + <listitem> + <para> + Prevent dropping a foreign-key constraint if there are pending + trigger events for the referenced relation (Tom Lane) + </para> + + <para> + This avoids <quote>could not find trigger <replaceable>NNN</></quote> + or <quote>relation <replaceable>NNN</> has no triggers</quote> errors. + </para> + </listitem> + + <listitem> + <para> + Fix processing of OID column when a table with OIDs is associated to + a parent with OIDs via <command>ALTER TABLE ... INHERIT</> (Amit + Langote) + </para> + + <para> + The OID column should be treated the same as regular user columns in + this case, but it wasn't, leading to odd behavior in later + inheritance changes. + </para> + </listitem> + + <listitem> + <para> + Check for serializability conflicts before reporting + constraint-violation failures (Thomas Munro) + </para> + + <para> + When using serializable transaction isolation, it is desirable + that any error due to concurrent transactions should manifest + as a serialization failure, thereby cueing the application that + a retry might succeed. Unfortunately, this does not reliably + happen for duplicate-key failures caused by concurrent insertions. + This change ensures that such an error will be reported as a + serialization error if the application explicitly checked for + the presence of a conflicting key (and did not find it) earlier + in the transaction. + </para> + </listitem> + + <listitem> + <para> + Ensure that column typmods are determined accurately for + multi-row <literal>VALUES</> constructs (Tom Lane) + </para> + + <para> + This fixes problems occurring when the first value in a column has a + determinable typmod (e.g., length for a <type>varchar</> value) but + later values don't share the same limit. + </para> + </listitem> + + <listitem> + <para> + Throw error for an unfinished Unicode surrogate pair at the end of a + Unicode string (Tom Lane) + </para> + + <para> + Normally, a Unicode surrogate leading character must be followed by a + Unicode surrogate trailing character, but the check for this was + missed if the leading character was the last character in a Unicode + string literal (<literal>U&'...'</>) or Unicode identifier + (<literal>U&"..."</>). + </para> + </listitem> + + <listitem> + <para> + Ensure that a purely negative text search query, such + as <literal>!foo</>, matches empty <type>tsvector</>s (Tom Dunstan) + </para> + + <para> + Such matches were found by GIN index searches, but not by sequential + scans or GiST index searches. + </para> + </listitem> + + <listitem> + <para> + Prevent crash when <function>ts_rewrite()</> replaces a non-top-level + subtree with an empty query (Artur Zakirov) + </para> + </listitem> + + <listitem> + <para> + Fix performance problems in <function>ts_rewrite()</> (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix <function>ts_rewrite()</>'s handling of nested NOT operators + (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix <function>array_fill()</> to handle empty arrays properly (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix one-byte buffer overrun in <function>quote_literal_cstr()</> + (Heikki Linnakangas) + </para> + + <para> + The overrun occurred only if the input consisted entirely of single + quotes and/or backslashes. + </para> + </listitem> + + <listitem> + <para> + Prevent multiple calls of <function>pg_start_backup()</> + and <function>pg_stop_backup()</> from running concurrently (Michael + Paquier) + </para> + + <para> + This avoids an assertion failure, and possibly worse things, if + someone tries to run these functions in parallel. + </para> + </listitem> + + <listitem> + <para> + Avoid discarding <type>interval</>-to-<type>interval</> casts + that aren't really no-ops (Tom Lane) + </para> + + <para> + In some cases, a cast that should result in zeroing out + low-order <type>interval</> fields was mistakenly deemed to be a + no-op and discarded. An example is that casting from <type>INTERVAL + MONTH</> to <type>INTERVAL YEAR</> failed to clear the months field. + </para> + </listitem> + + <listitem> + <para> + Fix <application>pg_dump</> to dump user-defined casts and transforms + that use built-in functions (Stephen Frost) + </para> + </listitem> + + <listitem> + <para> + Fix possible <application>pg_basebackup</> failure on standby + server when including WAL files (Amit Kapila, Robert Haas) + </para> + </listitem> + + <listitem> + <para> + Ensure that the Python exception objects we create for PL/Python are + properly reference-counted (Rafa de la Torre, Tom Lane) + </para> + + <para> + This avoids failures if the objects are used after a Python garbage + collection cycle has occurred. + </para> + </listitem> + + <listitem> + <para> + Fix PL/Tcl to support triggers on tables that have <literal>.tupno</> + as a column name (Tom Lane) + </para> + + <para> + This matches the (previously undocumented) behavior of + PL/Tcl's <command>spi_exec</> and <command>spi_execp</> commands, + namely that a magic <literal>.tupno</> column is inserted only if + there isn't a real column named that. + </para> + </listitem> + + <listitem> + <para> + Allow DOS-style line endings in <filename>~/.pgpass</> files, + even on Unix (Vik Fearing) + </para> + + <para> + This change simplifies use of the same password file across Unix and + Windows machines. + </para> + </listitem> + + <listitem> + <para> + Fix one-byte buffer overrun if <application>ecpg</> is given a file + name that ends with a dot (Takayuki Tsunakawa) + </para> + </listitem> + + <listitem> + <para> + Fix <application>psql</>'s tab completion for <command>ALTER DEFAULT + PRIVILEGES</> (Gilles Darold, Stephen Frost) + </para> + </listitem> + + <listitem> + <para> + In <application>psql</>, treat an empty or all-blank setting of + the <envar>PAGER</> environment variable as meaning <quote>no + pager</> (Tom Lane) + </para> + + <para> + Previously, such a setting caused output intended for the pager to + vanish entirely. + </para> + </listitem> + + <listitem> + <para> + Improve <filename>contrib/dblink</>'s reporting of + low-level <application>libpq</> errors, such as out-of-memory + (Joe Conway) + </para> + </listitem> + + <listitem> + <para> + On Windows, ensure that environment variable changes are propagated + to DLLs built with debug options (Christian Ullrich) + </para> + </listitem> + + <listitem> + <para> + Sync our copy of the timezone library with IANA release tzcode2016j + (Tom Lane) + </para> + + <para> + This fixes various issues, most notably that timezone data + installation failed if the target directory didn't support hard + links. + </para> + </listitem> + + <listitem> + <para> + Update time zone data files to <application>tzdata</> release 2016j + for DST law changes in northern Cyprus (adding a new zone + Asia/Famagusta), Russia (adding a new zone Europe/Saratov), Tonga, + and Antarctica/Casey. + Historical corrections for Italy, Kazakhstan, Malta, and Palestine. + Switch to preferring numeric zone abbreviations for Tonga. + </para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + + <sect1 id="release-9-2-19"> + <title>Release 9.2.19</title> + + <formalpara> + <title>Release date:</title> + <para>2016-10-27</para> + </formalpara> + + <para> + This release contains a variety of fixes from 9.2.18. + For information about new features in the 9.2 major release, see + <xref linkend="release-9-2">. + </para> + + <sect2> + <title>Migration to Version 9.2.19</title> + + <para> + A dump/restore is not required for those running 9.2.X. + </para> + + <para> + However, if you are upgrading from a version earlier than 9.2.11, + see <xref linkend="release-9-2-11">. + </para> + + </sect2> + + <sect2> + <title>Changes</title> + + <itemizedlist> + + <listitem> + <para> + Fix EvalPlanQual rechecks involving CTE scans (Tom Lane) + </para> + + <para> + The recheck would always see the CTE as returning no rows, typically + leading to failure to update rows that were recently updated. + </para> + </listitem> + + <listitem> + <para> + Fix improper repetition of previous results from hashed aggregation in + a subquery (Andrew Gierth) + </para> + + <para> + The test to see if we can reuse a previously-computed hash table of + the aggregate state values neglected the possibility of an outer query + reference appearing in an aggregate argument expression. A change in + the value of such a reference should lead to recalculating the hash + table, but did not. + </para> + </listitem> + + <listitem> + <para> + Fix <command>EXPLAIN</> to emit valid XML when + <xref linkend="guc-track-io-timing"> is on (Markus Winand) + </para> + + <para> + Previously the XML output-format option produced syntactically invalid + tags such as <literal><I/O-Read-Time></>. That is now + rendered as <literal><I-O-Read-Time></>. + </para> + </listitem> + + <listitem> + <para> + Suppress printing of zeroes for unmeasured times + in <command>EXPLAIN</> (Maksim Milyutin) + </para> + + <para> + Certain option combinations resulted in printing zero values for times + that actually aren't ever measured in that combination. Our general + policy in <command>EXPLAIN</> is not to print such fields at all, so + do that consistently in all cases. + </para> + </listitem> + + <listitem> + <para> + Fix timeout length when <command>VACUUM</> is waiting for exclusive + table lock so that it can truncate the table (Simon Riggs) + </para> + + <para> + The timeout was meant to be 50 milliseconds, but it was actually only + 50 microseconds, causing <command>VACUUM</> to give up on truncation + much more easily than intended. Set it to the intended value. + </para> + </listitem> + + <listitem> + <para> + Fix bugs in merging inherited <literal>CHECK</> constraints while + creating or altering a table (Tom Lane, Amit Langote) + </para> + + <para> + Allow identical <literal>CHECK</> constraints to be added to a parent + and child table in either order. Prevent merging of a valid + constraint from the parent table with a <literal>NOT VALID</> + constraint on the child. Likewise, prevent merging of a <literal>NO + INHERIT</> child constraint with an inherited constraint. + </para> + </listitem> + + <listitem> + <para> + Remove artificial restrictions on the values accepted + by <function>numeric_in()</> and <function>numeric_recv()</> + (Tom Lane) + </para> + + <para> + We allow numeric values up to the limit of the storage format (more + than <literal>1e100000</>), so it seems fairly pointless + that <function>numeric_in()</> rejected scientific-notation exponents + above 1000. Likewise, it was silly for <function>numeric_recv()</> to + reject more than 1000 digits in an input value. + </para> + </listitem> + + <listitem> + <para> + Avoid very-low-probability data corruption due to testing tuple + visibility without holding buffer lock (Thomas Munro, Peter Geoghegan, + Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix file descriptor leakage when truncating a temporary relation of + more than 1GB (Andres Freund) + </para> + </listitem> + + <listitem> + <para> + Disallow starting a standalone backend with <literal>standby_mode</> + turned on (Michael Paquier) + </para> + + <para> + This can't do anything useful, since there will be no WAL receiver + process to fetch more WAL data; and it could result in misbehavior + in code that wasn't designed with this situation in mind. + </para> + </listitem> + + <listitem> + <para> + Don't try to share SSL contexts across multiple connections + in <application>libpq</> (Heikki Linnakangas) + </para> + + <para> + This led to assorted corner-case bugs, particularly when trying to use + different SSL parameters for different connections. + </para> + </listitem> + + <listitem> + <para> + Avoid corner-case memory leak in <application>libpq</> (Tom Lane) + </para> + + <para> + The reported problem involved leaking an error report + during <function>PQreset()</>, but there might be related cases. + </para> + </listitem> + + <listitem> + <para> + Make <application>ecpg</>'s <option>--help</> and <option>--version</> + options work consistently with our other executables (Haribabu Kommi) + </para> + </listitem> + + <listitem> + <para> + In <application>pg_dump</>, never dump range constructor functions + (Tom Lane) + </para> + + <para> + This oversight led to <application>pg_upgrade</> failures with + extensions containing range types, due to duplicate creation of the + constructor functions. + </para> + </listitem> + + <listitem> + <para> + Fix <filename>contrib/intarray/bench/bench.pl</> to print the results + of the <command>EXPLAIN</> it does when given the <option>-e</> option + (Daniel Gustafsson) + </para> + </listitem> + + <listitem> + <para> + Update Windows time zone mapping to recognize some time zone names + added in recent Windows versions (Michael Paquier) + </para> + </listitem> + + <listitem> + <para> + Prevent failure of obsolete dynamic time zone abbreviations (Tom Lane) + </para> + + <para> + If a dynamic time zone abbreviation does not match any entry in the + referenced time zone, treat it as equivalent to the time zone name. + This avoids unexpected failures when IANA removes abbreviations from + their time zone database, as they did in <application>tzdata</> + release 2016f and seem likely to do again in the future. The + consequences were not limited to not recognizing the individual + abbreviation; any mismatch caused + the <structname>pg_timezone_abbrevs</> view to fail altogether. + </para> + </listitem> + + <listitem> + <para> + Update time zone data files to <application>tzdata</> release 2016h + for DST law changes in Palestine and Turkey, plus historical + corrections for Turkey and some regions of Russia. + Switch to numeric abbreviations for some time zones in Antarctica, + the former Soviet Union, and Sri Lanka. + </para> + + <para> + The IANA time zone database previously provided textual abbreviations + for all time zones, sometimes making up abbreviations that have little + or no currency among the local population. They are in process of + reversing that policy in favor of using numeric UTC offsets in zones + where there is no evidence of real-world use of an English + abbreviation. At least for the time being, <productname>PostgreSQL</> + will continue to accept such removed abbreviations for timestamp input. + But they will not be shown in the <structname>pg_timezone_names</> + view nor used for output. + </para> + + <para> + In this update, <literal>AMT</> is no longer shown as being in use to + mean Armenia Time. Therefore, we have changed the <literal>Default</> + abbreviation set to interpret it as Amazon Time, thus UTC-4 not UTC+4. + </para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + <sect1 id="release-9-2-18"> <title>Release 9.2.18</title> - <note> - <title>Release Date</title> - <simpara>2016-08-11</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-08-11</para> + </formalpara> <para> This release contains a variety of fixes from 9.2.17. @@ -345,10 +1471,10 @@ <sect1 id="release-9-2-17"> <title>Release 9.2.17</title> - <note> - <title>Release Date</title> - <simpara>2016-05-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-05-12</para> + </formalpara> <para> This release contains a variety of fixes from 9.2.16. @@ -541,10 +1667,10 @@ <sect1 id="release-9-2-16"> <title>Release 9.2.16</title> - <note> - <title>Release Date</title> - <simpara>2016-03-31</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-03-31</para> + </formalpara> <para> This release contains a variety of fixes from 9.2.15. @@ -629,7 +1755,7 @@ <para> This dodges a portability problem on FreeBSD-derived platforms - (including OS X). + (including macOS). </para> </listitem> @@ -747,10 +1873,10 @@ <sect1 id="release-9-2-15"> <title>Release 9.2.15</title> - <note> - <title>Release Date</title> - <simpara>2016-02-11</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-02-11</para> + </formalpara> <para> This release contains a variety of fixes from 9.2.14. @@ -1291,10 +2417,10 @@ <sect1 id="release-9-2-14"> <title>Release 9.2.14</title> - <note> - <title>Release Date</title> - <simpara>2015-10-08</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-10-08</para> + </formalpara> <para> This release contains a variety of fixes from 9.2.13. @@ -1888,10 +3014,10 @@ Branch: REL9_2_STABLE [e90a629e1] 2015-09-22 14:58:38 -0700 <sect1 id="release-9-2-13"> <title>Release 9.2.13</title> - <note> - <title>Release Date</title> - <simpara>2015-06-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-06-12</para> + </formalpara> <para> This release contains a small number of fixes from 9.2.12. @@ -1956,10 +3082,10 @@ Branch: REL9_2_STABLE [e90a629e1] 2015-09-22 14:58:38 -0700 <sect1 id="release-9-2-12"> <title>Release 9.2.12</title> - <note> - <title>Release Date</title> - <simpara>2015-06-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-06-04</para> + </formalpara> <para> This release contains a small number of fixes from 9.2.11. @@ -2051,10 +3177,10 @@ Branch: REL9_2_STABLE [e90a629e1] 2015-09-22 14:58:38 -0700 <sect1 id="release-9-2-11"> <title>Release 9.2.11</title> - <note> - <title>Release Date</title> - <simpara>2015-05-22</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-05-22</para> + </formalpara> <para> This release contains a variety of fixes from 9.2.10. @@ -2633,10 +3759,10 @@ Branch: REL9_2_STABLE [6b700301c] 2015-02-17 16:03:00 +0100 <sect1 id="release-9-2-10"> <title>Release 9.2.10</title> - <note> - <title>Release Date</title> - <simpara>2015-02-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-02-05</para> + </formalpara> <para> This release contains a variety of fixes from 9.2.9. @@ -3190,7 +4316,7 @@ Branch: REL9_2_STABLE [6b700301c] 2015-02-17 16:03:00 +0100 <listitem> <para> - Warn if OS X's <function>setlocale()</> starts an unwanted extra + Warn if macOS's <function>setlocale()</> starts an unwanted extra thread inside the postmaster (Noah Misch) </para> </listitem> @@ -3550,10 +4676,10 @@ Branch: REL9_2_STABLE [6b700301c] 2015-02-17 16:03:00 +0100 <sect1 id="release-9-2-9"> <title>Release 9.2.9</title> - <note> - <title>Release Date</title> - <simpara>2014-07-24</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2014-07-24</para> + </formalpara> <para> This release contains a variety of fixes from 9.2.8. @@ -3899,7 +5025,7 @@ Branch: REL9_2_STABLE [6b700301c] 2015-02-17 16:03:00 +0100 <listitem> <para> - Fix linking of <application>libpython</> on OS X (Tom Lane) + Fix linking of <application>libpython</> on macOS (Tom Lane) </para> <para> @@ -4031,10 +5157,10 @@ Branch: REL9_2_STABLE [6b700301c] 2015-02-17 16:03:00 +0100 <sect1 id="release-9-2-8"> <title>Release 9.2.8</title> - <note> - <title>Release Date</title> - <simpara>2014-03-20</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2014-03-20</para> + </formalpara> <para> This release contains a variety of fixes from 9.2.7. @@ -4096,7 +5222,7 @@ Branch: REL9_2_STABLE [6b700301c] 2015-02-17 16:03:00 +0100 <para> This prevents scenarios wherein a pathological regular expression - could lock up a server process uninterruptably for a long time. + could lock up a server process uninterruptibly for a long time. </para> </listitem> @@ -4220,10 +5346,10 @@ Branch: REL9_2_STABLE [6b700301c] 2015-02-17 16:03:00 +0100 <sect1 id="release-9-2-7"> <title>Release 9.2.7</title> - <note> - <title>Release Date</title> - <simpara>2014-02-20</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2014-02-20</para> + </formalpara> <para> This release contains a variety of fixes from 9.2.6. @@ -4827,10 +5953,10 @@ Branch: REL9_2_STABLE [6b700301c] 2015-02-17 16:03:00 +0100 <sect1 id="release-9-2-6"> <title>Release 9.2.6</title> - <note> - <title>Release Date</title> - <simpara>2013-12-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-12-05</para> + </formalpara> <para> This release contains a variety of fixes from 9.2.5. @@ -5164,10 +6290,10 @@ Branch: REL9_2_STABLE [6b700301c] 2015-02-17 16:03:00 +0100 <sect1 id="release-9-2-5"> <title>Release 9.2.5</title> - <note> - <title>Release Date</title> - <simpara>2013-10-10</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-10-10</para> + </formalpara> <para> This release contains a variety of fixes from 9.2.4. @@ -5583,10 +6709,10 @@ Branch: REL9_2_STABLE [6b700301c] 2015-02-17 16:03:00 +0100 <sect1 id="release-9-2-4"> <title>Release 9.2.4</title> - <note> - <title>Release Date</title> - <simpara>2013-04-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-04-04</para> + </formalpara> <para> This release contains a variety of fixes from 9.2.3. @@ -5990,10 +7116,10 @@ Branch: REL9_2_STABLE [6b700301c] 2015-02-17 16:03:00 +0100 <sect1 id="release-9-2-3"> <title>Release 9.2.3</title> - <note> - <title>Release Date</title> - <simpara>2013-02-07</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-02-07</para> + </formalpara> <para> This release contains a variety of fixes from 9.2.2. @@ -6441,10 +7567,10 @@ Branch: REL9_2_STABLE [6b700301c] 2015-02-17 16:03:00 +0100 <sect1 id="release-9-2-2"> <title>Release 9.2.2</title> - <note> - <title>Release Date</title> - <simpara>2012-12-06</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-12-06</para> + </formalpara> <para> This release contains a variety of fixes from 9.2.1. @@ -7165,10 +8291,10 @@ Branch: REL9_2_STABLE [6b700301c] 2015-02-17 16:03:00 +0100 <sect1 id="release-9-2-1"> <title>Release 9.2.1</title> - <note> - <title>Release Date</title> - <simpara>2012-09-24</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-09-24</para> + </formalpara> <para> This release contains a variety of fixes from 9.2.0. @@ -7333,10 +8459,10 @@ Branch: REL9_2_STABLE [6b700301c] 2015-02-17 16:03:00 +0100 <sect1 id="release-9-2"> <title>Release 9.2</title> - <note> - <title>Release Date</title> - <simpara>2012-09-10</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2012-09-10</para> + </formalpara> <sect2> <title>Overview</title> @@ -7391,7 +8517,7 @@ Branch: REL9_2_STABLE [6b700301c] 2015-02-17 16:03:00 +0100 <listitem> <para> Add a <link - linkend="app-pgreceivexlog"><application>pg_receivexlog</></link> + linkend="app-pgreceivewal"><application>pg_receivexlog</></link> tool to archive WAL file changes as they are written </para> </listitem> @@ -8553,7 +9679,7 @@ Branch: REL9_2_STABLE [6b700301c] 2015-02-17 16:03:00 +0100 <listitem> <para> Add a <link - linkend="app-pgreceivexlog"><application>pg_receivexlog</></link> + linkend="app-pgreceivewal"><application>pg_receivexlog</></link> tool to archive WAL file changes as they are written, rather than waiting for completed WAL files (Magnus Hagander) </para> diff --git a/doc/src/sgml/release-9.3.sgml b/doc/src/sgml/release-9.3.sgml index c75f1109e1..86c1ae6d3f 100644 --- a/doc/src/sgml/release-9.3.sgml +++ b/doc/src/sgml/release-9.3.sgml @@ -1,13 +1,1277 @@ <!-- doc/src/sgml/release-9.3.sgml --> <!-- See header comment in release.sgml about typical markup --> + <sect1 id="release-9-3-17"> + <title>Release 9.3.17</title> + + <formalpara> + <title>Release date:</title> + <para>2017-05-11</para> + </formalpara> + + <para> + This release contains a variety of fixes from 9.3.16. + For information about new features in the 9.3 major release, see + <xref linkend="release-9-3">. + </para> + + <sect2> + <title>Migration to Version 9.3.17</title> + + <para> + A dump/restore is not required for those running 9.3.X. + </para> + + <para> + However, if you use foreign data servers that make use of user + passwords for authentication, see the first changelog entry below. + </para> + + <para> + Also, if you are upgrading from a version earlier than 9.3.16, + see <xref linkend="release-9-3-16">. + </para> + + </sect2> + + <sect2> + <title>Changes</title> + + <itemizedlist> + + <listitem> + <para> + Restrict visibility + of <structname>pg_user_mappings</>.<structfield>umoptions</>, to + protect passwords stored as user mapping options + (Michael Paquier, Feike Steenbergen) + </para> + + <para> + The previous coding allowed the owner of a foreign server object, + or anyone he has granted server <literal>USAGE</> permission to, + to see the options for all user mappings associated with that server. + This might well include passwords for other users. + Adjust the view definition to match the behavior of + <structname>information_schema.user_mapping_options</>, namely that + these options are visible to the user being mapped, or if the mapping + is for <literal>PUBLIC</literal> and the current user is the server + owner, or if the current user is a superuser. + (CVE-2017-7486) + </para> + + <para> + By itself, this patch will only fix the behavior in newly initdb'd + databases. If you wish to apply this change in an existing database, + you will need to do the following: + </para> + + <procedure> + <step> + <para> + Restart the postmaster after adding <literal>allow_system_table_mods + = true</> to <filename>postgresql.conf</>. (In versions + supporting <command>ALTER SYSTEM</>, you can use that to make the + configuration change, but you'll still need a restart.) + </para> + </step> + + <step> + <para> + In <emphasis>each</> database of the cluster, + run the following commands as superuser: +<programlisting> +SET search_path = pg_catalog; +CREATE OR REPLACE VIEW pg_user_mappings AS + SELECT + U.oid AS umid, + S.oid AS srvid, + S.srvname AS srvname, + U.umuser AS umuser, + CASE WHEN U.umuser = 0 THEN + 'public' + ELSE + A.rolname + END AS usename, + CASE WHEN (U.umuser <> 0 AND A.rolname = current_user) + OR (U.umuser = 0 AND pg_has_role(S.srvowner, 'USAGE')) + OR (SELECT rolsuper FROM pg_authid WHERE rolname = current_user) + THEN U.umoptions + ELSE NULL END AS umoptions + FROM pg_user_mapping U + LEFT JOIN pg_authid A ON (A.oid = U.umuser) JOIN + pg_foreign_server S ON (U.umserver = S.oid); +</programlisting> + </para> + </step> + + <step> + <para> + Do not forget to include the <literal>template0</> + and <literal>template1</> databases, or the vulnerability will still + exist in databases you create later. To fix <literal>template0</>, + you'll need to temporarily make it accept connections. + In <productname>PostgreSQL</> 9.5 and later, you can use +<programlisting> +ALTER DATABASE template0 WITH ALLOW_CONNECTIONS true; +</programlisting> + and then after fixing <literal>template0</>, undo that with +<programlisting> +ALTER DATABASE template0 WITH ALLOW_CONNECTIONS false; +</programlisting> + In prior versions, instead use +<programlisting> +UPDATE pg_database SET datallowconn = true WHERE datname = 'template0'; +UPDATE pg_database SET datallowconn = false WHERE datname = 'template0'; +</programlisting> + </para> + </step> + + <step> + <para> + Finally, remove the <literal>allow_system_table_mods</> configuration + setting, and again restart the postmaster. + </para> + </step> + </procedure> + </listitem> + + <listitem> + <para> + Prevent exposure of statistical information via leaky operators + (Peter Eisentraut) + </para> + + <para> + Some selectivity estimation functions in the planner will apply + user-defined operators to values obtained + from <structname>pg_statistic</>, such as most common values and + histogram entries. This occurs before table permissions are checked, + so a nefarious user could exploit the behavior to obtain these values + for table columns he does not have permission to read. To fix, + fall back to a default estimate if the operator's implementation + function is not certified leak-proof and the calling user does not have + permission to read the table column whose statistics are needed. + At least one of these criteria is satisfied in most cases in practice. + (CVE-2017-7484) + </para> + </listitem> + + <listitem> + <para> + Restore <application>libpq</>'s recognition of + the <envar>PGREQUIRESSL</> environment variable (Daniel Gustafsson) + </para> + + <para> + Processing of this environment variable was unintentionally dropped + in <productname>PostgreSQL</> 9.3, but its documentation remained. + This creates a security hazard, since users might be relying on the + environment variable to force SSL-encrypted connections, but that + would no longer be guaranteed. Restore handling of the variable, + but give it lower priority than <envar>PGSSLMODE</>, to avoid + breaking configurations that work correctly with post-9.3 code. + (CVE-2017-7485) + </para> + </listitem> + + <listitem> + <para> + Fix possible corruption of <quote>init forks</> of unlogged indexes + (Robert Haas, Michael Paquier) + </para> + + <para> + This could result in an unlogged index being set to an invalid state + after a crash and restart. Such a problem would persist until the + index was dropped and rebuilt. + </para> + </listitem> + + <listitem> + <para> + Fix incorrect reconstruction of <structname>pg_subtrans</> entries + when a standby server replays a prepared but uncommitted two-phase + transaction (Tom Lane) + </para> + + <para> + In most cases this turned out to have no visible ill effects, but in + corner cases it could result in circular references + in <structname>pg_subtrans</>, potentially causing infinite loops + in queries that examine rows modified by the two-phase transaction. + </para> + </listitem> + + <listitem> + <para> + Ensure parsing of queries in extension scripts sees the results of + immediately-preceding DDL (Julien Rouhaud, Tom Lane) + </para> + + <para> + Due to lack of a cache flush step between commands in an extension + script file, non-utility queries might not see the effects of an + immediately preceding catalog change, such as <command>ALTER TABLE + ... RENAME</>. + </para> + </listitem> + + <listitem> + <para> + Skip tablespace privilege checks when <command>ALTER TABLE ... ALTER + COLUMN TYPE</> rebuilds an existing index (Noah Misch) + </para> + + <para> + The command failed if the calling user did not currently have + <literal>CREATE</> privilege for the tablespace containing the index. + That behavior seems unhelpful, so skip the check, allowing the + index to be rebuilt where it is. + </para> + </listitem> + + <listitem> + <para> + Fix <command>ALTER TABLE ... VALIDATE CONSTRAINT</> to not recurse + to child tables when the constraint is marked <literal>NO INHERIT</> + (Amit Langote) + </para> + + <para> + This fix prevents unwanted <quote>constraint does not exist</> failures + when no matching constraint is present in the child tables. + </para> + </listitem> + + <listitem> + <para> + Fix <command>VACUUM</> to account properly for pages that could not + be scanned due to conflicting page pins (Andrew Gierth) + </para> + + <para> + This tended to lead to underestimation of the number of tuples in + the table. In the worst case of a small heavily-contended + table, <command>VACUUM</> could incorrectly report that the table + contained no tuples, leading to very bad planning choices. + </para> + </listitem> + + <listitem> + <para> + Ensure that bulk-tuple-transfer loops within a hash join are + interruptible by query cancel requests (Tom Lane, Thomas Munro) + </para> + </listitem> + + <listitem> + <para> + Fix <function>cursor_to_xml()</> to produce valid output + with <replaceable>tableforest</> = false + (Thomas Munro, Peter Eisentraut) + </para> + + <para> + Previously it failed to produce a wrapping <literal><table></> + element. + </para> + </listitem> + + <listitem> + <para> + Improve performance of <structname>pg_timezone_names</> view + (Tom Lane, David Rowley) + </para> + </listitem> + + <listitem> + <para> + Fix sloppy handling of corner-case errors from <function>lseek()</> + and <function>close()</> (Tom Lane) + </para> + + <para> + Neither of these system calls are likely to fail in typical situations, + but if they did, <filename>fd.c</> could get quite confused. + </para> + </listitem> + + <listitem> + <para> + Fix incorrect check for whether postmaster is running as a Windows + service (Michael Paquier) + </para> + + <para> + This could result in attempting to write to the event log when that + isn't accessible, so that no logging happens at all. + </para> + </listitem> + + <listitem> + <para> + Fix <application>ecpg</> to support <command>COMMIT PREPARED</> + and <command>ROLLBACK PREPARED</> (Masahiko Sawada) + </para> + </listitem> + + <listitem> + <para> + Fix a double-free error when processing dollar-quoted string literals + in <application>ecpg</> (Michael Meskes) + </para> + </listitem> + + <listitem> + <para> + In <application>pg_dump</>, fix incorrect schema and owner marking for + comments and security labels of some types of database objects + (Giuseppe Broccolo, Tom Lane) + </para> + + <para> + In simple cases this caused no ill effects; but for example, a + schema-selective restore might omit comments it should include, because + they were not marked as belonging to the schema of their associated + object. + </para> + </listitem> + + <listitem> + <para> + Avoid emitting an invalid list file in <literal>pg_restore -l</> + when SQL object names contain newlines (Tom Lane) + </para> + + <para> + Replace newlines by spaces, which is sufficient to make the output + valid for <literal>pg_restore -L</>'s purposes. + </para> + </listitem> + + <listitem> + <para> + Fix <application>pg_upgrade</> to transfer comments and security labels + attached to <quote>large objects</> (blobs) (Stephen Frost) + </para> + + <para> + Previously, blobs were correctly transferred to the new database, but + any comments or security labels attached to them were lost. + </para> + </listitem> + + <listitem> + <para> + Improve error handling + in <filename>contrib/adminpack</>'s <function>pg_file_write()</> + function (Noah Misch) + </para> + + <para> + Notably, it failed to detect errors reported + by <function>fclose()</>. + </para> + </listitem> + + <listitem> + <para> + In <filename>contrib/dblink</>, avoid leaking the previous unnamed + connection when establishing a new unnamed connection (Joe Conway) + </para> + </listitem> + + <listitem> + <para> + Fix <filename>contrib/pg_trgm</>'s extraction of trigrams from regular + expressions (Tom Lane) + </para> + + <para> + In some cases it would produce a broken data structure that could never + match anything, leading to GIN or GiST indexscans that use a trigram + index not finding any matches to the regular expression. + </para> + </listitem> + + <listitem> + <para> + In <filename>contrib/postgres_fdw</>, + transmit query cancellation requests to the remote server + (Michael Paquier, Etsuro Fujita) + </para> + + <para> + Previously, a local query cancellation request did not cause an + already-sent remote query to terminate early. This is a back-patch + of work originally done for 9.6. + </para> + </listitem> + + <listitem> + <para> + Support OpenSSL 1.1.0 (Heikki Linnakangas, Andreas Karlsson, Tom Lane) + </para> + + <para> + This is a back-patch of work previously done in newer branches; + it's needed since many platforms are adopting newer OpenSSL versions. + </para> + </listitem> + + <listitem> + <para> + Support Tcl 8.6 in MSVC builds (Álvaro Herrera) + </para> + </listitem> + + <listitem> + <para> + Sync our copy of the timezone library with IANA release tzcode2017b + (Tom Lane) + </para> + + <para> + This fixes a bug affecting some DST transitions in January 2038. + </para> + </listitem> + + <listitem> + <para> + Update time zone data files to <application>tzdata</> release 2017b + for DST law changes in Chile, Haiti, and Mongolia, plus historical + corrections for Ecuador, Kazakhstan, Liberia, and Spain. + Switch to numeric abbreviations for numerous time zones in South + America, the Pacific and Indian oceans, and some Asian and Middle + Eastern countries. + </para> + + <para> + The IANA time zone database previously provided textual abbreviations + for all time zones, sometimes making up abbreviations that have little + or no currency among the local population. They are in process of + reversing that policy in favor of using numeric UTC offsets in zones + where there is no evidence of real-world use of an English + abbreviation. At least for the time being, <productname>PostgreSQL</> + will continue to accept such removed abbreviations for timestamp input. + But they will not be shown in the <structname>pg_timezone_names</> + view nor used for output. + </para> + </listitem> + + <listitem> + <para> + Use correct daylight-savings rules for POSIX-style time zone names + in MSVC builds (David Rowley) + </para> + + <para> + The Microsoft MSVC build scripts neglected to install + the <filename>posixrules</> file in the timezone directory tree. + This resulted in the timezone code falling back to its built-in + rule about what DST behavior to assume for a POSIX-style time zone + name. For historical reasons that still corresponds to the DST rules + the USA was using before 2007 (i.e., change on first Sunday in April + and last Sunday in October). With this fix, a POSIX-style zone name + will use the current and historical DST transition dates of + the <literal>US/Eastern</> zone. If you don't want that, remove + the <filename>posixrules</> file, or replace it with a copy of some + other zone file (see <xref linkend="datatype-timezones">). Note that + due to caching, you may need to restart the server to get such changes + to take effect. + </para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + + <sect1 id="release-9-3-16"> + <title>Release 9.3.16</title> + + <formalpara> + <title>Release date:</title> + <para>2017-02-09</para> + </formalpara> + + <para> + This release contains a variety of fixes from 9.3.15. + For information about new features in the 9.3 major release, see + <xref linkend="release-9-3">. + </para> + + <sect2> + <title>Migration to Version 9.3.16</title> + + <para> + A dump/restore is not required for those running 9.3.X. + </para> + + <para> + However, if your installation has been affected by the bug described in + the first changelog entry below, then after updating you may need + to take action to repair corrupted indexes. + </para> + + <para> + Also, if you are upgrading from a version earlier than 9.3.15, + see <xref linkend="release-9-3-15">. + </para> + + </sect2> + + <sect2> + <title>Changes</title> + + <itemizedlist> + + <listitem> + <para> + Fix a race condition that could cause indexes built + with <command>CREATE INDEX CONCURRENTLY</> to be corrupt + (Pavan Deolasee, Tom Lane) + </para> + + <para> + If <command>CREATE INDEX CONCURRENTLY</> was used to build an index + that depends on a column not previously indexed, then rows + updated by transactions that ran concurrently with + the <command>CREATE INDEX</> command could have received incorrect + index entries. If you suspect this may have happened, the most + reliable solution is to rebuild affected indexes after installing + this update. + </para> + </listitem> + + <listitem> + <para> + Unconditionally WAL-log creation of the <quote>init fork</> for an + unlogged table (Michael Paquier) + </para> + + <para> + Previously, this was skipped when <xref linkend="guc-wal-level"> + = <literal>minimal</>, but actually it's necessary even in that case + to ensure that the unlogged table is properly reset to empty after a + crash. + </para> + </listitem> + + <listitem> + <para> + If the stats collector dies during hot standby, restart it (Takayuki + Tsunakawa) + </para> + </listitem> + + <listitem> + <para> + Ensure that hot standby feedback works correctly when it's enabled at + standby server start (Ants Aasma, Craig Ringer) + </para> + </listitem> + + <listitem> + <para> + Check for interrupts while hot standby is waiting for a conflicting + query (Simon Riggs) + </para> + </listitem> + + <listitem> + <para> + Avoid constantly respawning the autovacuum launcher in a corner case + (Amit Khandekar) + </para> + + <para> + This fix avoids problems when autovacuum is nominally off and there + are some tables that require freezing, but all such tables are + already being processed by autovacuum workers. + </para> + </listitem> + + <listitem> + <para> + Fix check for when an extension member object can be dropped (Tom Lane) + </para> + + <para> + Extension upgrade scripts should be able to drop member objects, + but this was disallowed for serial-column sequences, and possibly + other cases. + </para> + </listitem> + + <listitem> + <para> + Make sure <command>ALTER TABLE</> preserves index tablespace + assignments when rebuilding indexes (Tom Lane, Michael Paquier) + </para> + + <para> + Previously, non-default settings + of <xref linkend="guc-default-tablespace"> could result in broken + indexes. + </para> + </listitem> + + <listitem> + <para> + Prevent dropping a foreign-key constraint if there are pending + trigger events for the referenced relation (Tom Lane) + </para> + + <para> + This avoids <quote>could not find trigger <replaceable>NNN</></quote> + or <quote>relation <replaceable>NNN</> has no triggers</quote> errors. + </para> + </listitem> + + <listitem> + <para> + Fix processing of OID column when a table with OIDs is associated to + a parent with OIDs via <command>ALTER TABLE ... INHERIT</> (Amit + Langote) + </para> + + <para> + The OID column should be treated the same as regular user columns in + this case, but it wasn't, leading to odd behavior in later + inheritance changes. + </para> + </listitem> + + <listitem> + <para> + Report correct object identity during <command>ALTER TEXT SEARCH + CONFIGURATION</> (Artur Zakirov) + </para> + + <para> + The wrong catalog OID was reported to extensions such as logical + decoding. + </para> + </listitem> + + <listitem> + <para> + Check for serializability conflicts before reporting + constraint-violation failures (Thomas Munro) + </para> + + <para> + When using serializable transaction isolation, it is desirable + that any error due to concurrent transactions should manifest + as a serialization failure, thereby cueing the application that + a retry might succeed. Unfortunately, this does not reliably + happen for duplicate-key failures caused by concurrent insertions. + This change ensures that such an error will be reported as a + serialization error if the application explicitly checked for + the presence of a conflicting key (and did not find it) earlier + in the transaction. + </para> + </listitem> + + <listitem> + <para> + Prevent multicolumn expansion of <replaceable>foo</><literal>.*</> in + an <command>UPDATE</> source expression (Tom Lane) + </para> + + <para> + This led to <quote>UPDATE target count mismatch --- internal + error</>. Now the syntax is understood as a whole-row variable, + as it would be in other contexts. + </para> + </listitem> + + <listitem> + <para> + Ensure that column typmods are determined accurately for + multi-row <literal>VALUES</> constructs (Tom Lane) + </para> + + <para> + This fixes problems occurring when the first value in a column has a + determinable typmod (e.g., length for a <type>varchar</> value) but + later values don't share the same limit. + </para> + </listitem> + + <listitem> + <para> + Throw error for an unfinished Unicode surrogate pair at the end of a + Unicode string (Tom Lane) + </para> + + <para> + Normally, a Unicode surrogate leading character must be followed by a + Unicode surrogate trailing character, but the check for this was + missed if the leading character was the last character in a Unicode + string literal (<literal>U&'...'</>) or Unicode identifier + (<literal>U&"..."</>). + </para> + </listitem> + + <listitem> + <para> + Ensure that a purely negative text search query, such + as <literal>!foo</>, matches empty <type>tsvector</>s (Tom Dunstan) + </para> + + <para> + Such matches were found by GIN index searches, but not by sequential + scans or GiST index searches. + </para> + </listitem> + + <listitem> + <para> + Prevent crash when <function>ts_rewrite()</> replaces a non-top-level + subtree with an empty query (Artur Zakirov) + </para> + </listitem> + + <listitem> + <para> + Fix performance problems in <function>ts_rewrite()</> (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix <function>ts_rewrite()</>'s handling of nested NOT operators + (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix <function>array_fill()</> to handle empty arrays properly (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix one-byte buffer overrun in <function>quote_literal_cstr()</> + (Heikki Linnakangas) + </para> + + <para> + The overrun occurred only if the input consisted entirely of single + quotes and/or backslashes. + </para> + </listitem> + + <listitem> + <para> + Prevent multiple calls of <function>pg_start_backup()</> + and <function>pg_stop_backup()</> from running concurrently (Michael + Paquier) + </para> + + <para> + This avoids an assertion failure, and possibly worse things, if + someone tries to run these functions in parallel. + </para> + </listitem> + + <listitem> + <para> + Avoid discarding <type>interval</>-to-<type>interval</> casts + that aren't really no-ops (Tom Lane) + </para> + + <para> + In some cases, a cast that should result in zeroing out + low-order <type>interval</> fields was mistakenly deemed to be a + no-op and discarded. An example is that casting from <type>INTERVAL + MONTH</> to <type>INTERVAL YEAR</> failed to clear the months field. + </para> + </listitem> + + <listitem> + <para> + Ensure that cached plans are invalidated by changes in foreign-table + options (Amit Langote, Etsuro Fujita, Ashutosh Bapat) + </para> + </listitem> + + <listitem> + <para> + Fix <application>pg_dump</> to dump user-defined casts and transforms + that use built-in functions (Stephen Frost) + </para> + </listitem> + + <listitem> + <para> + Fix possible <application>pg_basebackup</> failure on standby + server when including WAL files (Amit Kapila, Robert Haas) + </para> + </listitem> + + <listitem> + <para> + Ensure that the Python exception objects we create for PL/Python are + properly reference-counted (Rafa de la Torre, Tom Lane) + </para> + + <para> + This avoids failures if the objects are used after a Python garbage + collection cycle has occurred. + </para> + </listitem> + + <listitem> + <para> + Fix PL/Tcl to support triggers on tables that have <literal>.tupno</> + as a column name (Tom Lane) + </para> + + <para> + This matches the (previously undocumented) behavior of + PL/Tcl's <command>spi_exec</> and <command>spi_execp</> commands, + namely that a magic <literal>.tupno</> column is inserted only if + there isn't a real column named that. + </para> + </listitem> + + <listitem> + <para> + Allow DOS-style line endings in <filename>~/.pgpass</> files, + even on Unix (Vik Fearing) + </para> + + <para> + This change simplifies use of the same password file across Unix and + Windows machines. + </para> + </listitem> + + <listitem> + <para> + Fix one-byte buffer overrun if <application>ecpg</> is given a file + name that ends with a dot (Takayuki Tsunakawa) + </para> + </listitem> + + <listitem> + <para> + Fix <application>psql</>'s tab completion for <command>ALTER DEFAULT + PRIVILEGES</> (Gilles Darold, Stephen Frost) + </para> + </listitem> + + <listitem> + <para> + In <application>psql</>, treat an empty or all-blank setting of + the <envar>PAGER</> environment variable as meaning <quote>no + pager</> (Tom Lane) + </para> + + <para> + Previously, such a setting caused output intended for the pager to + vanish entirely. + </para> + </listitem> + + <listitem> + <para> + Improve <filename>contrib/dblink</>'s reporting of + low-level <application>libpq</> errors, such as out-of-memory + (Joe Conway) + </para> + </listitem> + + <listitem> + <para> + Teach <filename>contrib/dblink</> to ignore irrelevant server options + when it uses a <filename>contrib/postgres_fdw</> foreign server as + the source of connection options (Corey Huinker) + </para> + + <para> + Previously, if the foreign server object had options that were not + also <application>libpq</> connection options, an error occurred. + </para> + </listitem> + + <listitem> + <para> + On Windows, ensure that environment variable changes are propagated + to DLLs built with debug options (Christian Ullrich) + </para> + </listitem> + + <listitem> + <para> + Sync our copy of the timezone library with IANA release tzcode2016j + (Tom Lane) + </para> + + <para> + This fixes various issues, most notably that timezone data + installation failed if the target directory didn't support hard + links. + </para> + </listitem> + + <listitem> + <para> + Update time zone data files to <application>tzdata</> release 2016j + for DST law changes in northern Cyprus (adding a new zone + Asia/Famagusta), Russia (adding a new zone Europe/Saratov), Tonga, + and Antarctica/Casey. + Historical corrections for Italy, Kazakhstan, Malta, and Palestine. + Switch to preferring numeric zone abbreviations for Tonga. + </para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + + <sect1 id="release-9-3-15"> + <title>Release 9.3.15</title> + + <formalpara> + <title>Release date:</title> + <para>2016-10-27</para> + </formalpara> + + <para> + This release contains a variety of fixes from 9.3.14. + For information about new features in the 9.3 major release, see + <xref linkend="release-9-3">. + </para> + + <sect2> + <title>Migration to Version 9.3.15</title> + + <para> + A dump/restore is not required for those running 9.3.X. + </para> + + <para> + However, if your installation has been affected by the bug described in + the first changelog entry below, then after updating you may need + to take action to repair corrupted free space maps. + </para> + + <para> + Also, if you are upgrading from a version earlier than 9.3.9, + see <xref linkend="release-9-3-9">. + </para> + + </sect2> + + <sect2> + <title>Changes</title> + + <itemizedlist> + + <listitem> + <para> + Fix WAL-logging of truncation of relation free space maps and + visibility maps (Pavan Deolasee, Heikki Linnakangas) + </para> + + <para> + It was possible for these files to not be correctly restored during + crash recovery, or to be written incorrectly on a standby server. + Bogus entries in a free space map could lead to attempts to access + pages that have been truncated away from the relation itself, typically + producing errors like <quote>could not read block <replaceable>XXX</>: + read only 0 of 8192 bytes</quote>. Checksum failures in the + visibility map are also possible, if checksumming is enabled. + </para> + + <para> + Procedures for determining whether there is a problem and repairing it + if so are discussed at + <ulink url="https://wiki.postgresql.org/wiki/Free_Space_Map_Problems"></>. + </para> + </listitem> + + <listitem> + <para> + Fix <command>SELECT FOR UPDATE/SHARE</> to correctly lock tuples that + have been updated by a subsequently-aborted transaction + (Álvaro Herrera) + </para> + + <para> + In 9.5 and later, the <command>SELECT</> would sometimes fail to + return such tuples at all. A failure has not been proven to occur in + earlier releases, but might be possible with concurrent updates. + </para> + </listitem> + + <listitem> + <para> + Fix EvalPlanQual rechecks involving CTE scans (Tom Lane) + </para> + + <para> + The recheck would always see the CTE as returning no rows, typically + leading to failure to update rows that were recently updated. + </para> + </listitem> + + <listitem> + <para> + Fix improper repetition of previous results from hashed aggregation in + a subquery (Andrew Gierth) + </para> + + <para> + The test to see if we can reuse a previously-computed hash table of + the aggregate state values neglected the possibility of an outer query + reference appearing in an aggregate argument expression. A change in + the value of such a reference should lead to recalculating the hash + table, but did not. + </para> + </listitem> + + <listitem> + <para> + Fix <command>EXPLAIN</> to emit valid XML when + <xref linkend="guc-track-io-timing"> is on (Markus Winand) + </para> + + <para> + Previously the XML output-format option produced syntactically invalid + tags such as <literal><I/O-Read-Time></>. That is now + rendered as <literal><I-O-Read-Time></>. + </para> + </listitem> + + <listitem> + <para> + Suppress printing of zeroes for unmeasured times + in <command>EXPLAIN</> (Maksim Milyutin) + </para> + + <para> + Certain option combinations resulted in printing zero values for times + that actually aren't ever measured in that combination. Our general + policy in <command>EXPLAIN</> is not to print such fields at all, so + do that consistently in all cases. + </para> + </listitem> + + <listitem> + <para> + Fix timeout length when <command>VACUUM</> is waiting for exclusive + table lock so that it can truncate the table (Simon Riggs) + </para> + + <para> + The timeout was meant to be 50 milliseconds, but it was actually only + 50 microseconds, causing <command>VACUUM</> to give up on truncation + much more easily than intended. Set it to the intended value. + </para> + </listitem> + + <listitem> + <para> + Fix bugs in merging inherited <literal>CHECK</> constraints while + creating or altering a table (Tom Lane, Amit Langote) + </para> + + <para> + Allow identical <literal>CHECK</> constraints to be added to a parent + and child table in either order. Prevent merging of a valid + constraint from the parent table with a <literal>NOT VALID</> + constraint on the child. Likewise, prevent merging of a <literal>NO + INHERIT</> child constraint with an inherited constraint. + </para> + </listitem> + + <listitem> + <para> + Remove artificial restrictions on the values accepted + by <function>numeric_in()</> and <function>numeric_recv()</> + (Tom Lane) + </para> + + <para> + We allow numeric values up to the limit of the storage format (more + than <literal>1e100000</>), so it seems fairly pointless + that <function>numeric_in()</> rejected scientific-notation exponents + above 1000. Likewise, it was silly for <function>numeric_recv()</> to + reject more than 1000 digits in an input value. + </para> + </listitem> + + <listitem> + <para> + Avoid very-low-probability data corruption due to testing tuple + visibility without holding buffer lock (Thomas Munro, Peter Geoghegan, + Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix file descriptor leakage when truncating a temporary relation of + more than 1GB (Andres Freund) + </para> + </listitem> + + <listitem> + <para> + Disallow starting a standalone backend with <literal>standby_mode</> + turned on (Michael Paquier) + </para> + + <para> + This can't do anything useful, since there will be no WAL receiver + process to fetch more WAL data; and it could result in misbehavior + in code that wasn't designed with this situation in mind. + </para> + </listitem> + + <listitem> + <para> + Don't try to share SSL contexts across multiple connections + in <application>libpq</> (Heikki Linnakangas) + </para> + + <para> + This led to assorted corner-case bugs, particularly when trying to use + different SSL parameters for different connections. + </para> + </listitem> + + <listitem> + <para> + Avoid corner-case memory leak in <application>libpq</> (Tom Lane) + </para> + + <para> + The reported problem involved leaking an error report + during <function>PQreset()</>, but there might be related cases. + </para> + </listitem> + + <listitem> + <para> + Make <application>ecpg</>'s <option>--help</> and <option>--version</> + options work consistently with our other executables (Haribabu Kommi) + </para> + </listitem> + + <listitem> + <para> + In <application>pg_dump</>, never dump range constructor functions + (Tom Lane) + </para> + + <para> + This oversight led to <application>pg_upgrade</> failures with + extensions containing range types, due to duplicate creation of the + constructor functions. + </para> + </listitem> + + <listitem> + <para> + In <application>pg_xlogdump</>, retry opening new WAL segments when + using <option>--follow</> option (Magnus Hagander) + </para> + + <para> + This allows for a possible delay in the server's creation of the next + segment. + </para> + </listitem> + + <listitem> + <para> + Fix <application>pg_xlogdump</> to cope with a WAL file that begins + with a continuation record spanning more than one page (Pavan + Deolasee) + </para> + </listitem> + + <listitem> + <para> + Fix <filename>contrib/intarray/bench/bench.pl</> to print the results + of the <command>EXPLAIN</> it does when given the <option>-e</> option + (Daniel Gustafsson) + </para> + </listitem> + + <listitem> + <para> + Update Windows time zone mapping to recognize some time zone names + added in recent Windows versions (Michael Paquier) + </para> + </listitem> + + <listitem> + <para> + Prevent failure of obsolete dynamic time zone abbreviations (Tom Lane) + </para> + + <para> + If a dynamic time zone abbreviation does not match any entry in the + referenced time zone, treat it as equivalent to the time zone name. + This avoids unexpected failures when IANA removes abbreviations from + their time zone database, as they did in <application>tzdata</> + release 2016f and seem likely to do again in the future. The + consequences were not limited to not recognizing the individual + abbreviation; any mismatch caused + the <structname>pg_timezone_abbrevs</> view to fail altogether. + </para> + </listitem> + + <listitem> + <para> + Update time zone data files to <application>tzdata</> release 2016h + for DST law changes in Palestine and Turkey, plus historical + corrections for Turkey and some regions of Russia. + Switch to numeric abbreviations for some time zones in Antarctica, + the former Soviet Union, and Sri Lanka. + </para> + + <para> + The IANA time zone database previously provided textual abbreviations + for all time zones, sometimes making up abbreviations that have little + or no currency among the local population. They are in process of + reversing that policy in favor of using numeric UTC offsets in zones + where there is no evidence of real-world use of an English + abbreviation. At least for the time being, <productname>PostgreSQL</> + will continue to accept such removed abbreviations for timestamp input. + But they will not be shown in the <structname>pg_timezone_names</> + view nor used for output. + </para> + + <para> + In this update, <literal>AMT</> is no longer shown as being in use to + mean Armenia Time. Therefore, we have changed the <literal>Default</> + abbreviation set to interpret it as Amazon Time, thus UTC-4 not UTC+4. + </para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + <sect1 id="release-9-3-14"> <title>Release 9.3.14</title> - <note> - <title>Release Date</title> - <simpara>2016-08-11</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-08-11</para> + </formalpara> <para> This release contains a variety of fixes from 9.3.13. @@ -494,10 +1758,10 @@ <sect1 id="release-9-3-13"> <title>Release 9.3.13</title> - <note> - <title>Release Date</title> - <simpara>2016-05-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-05-12</para> + </formalpara> <para> This release contains a variety of fixes from 9.3.12. @@ -724,10 +1988,10 @@ Branch: REL9_2_STABLE [37f30b251] 2016-04-18 13:19:52 -0400 <sect1 id="release-9-3-12"> <title>Release 9.3.12</title> - <note> - <title>Release Date</title> - <simpara>2016-03-31</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-03-31</para> + </formalpara> <para> This release contains a variety of fixes from 9.3.11. @@ -812,7 +2076,7 @@ Branch: REL9_2_STABLE [37f30b251] 2016-04-18 13:19:52 -0400 <para> This dodges a portability problem on FreeBSD-derived platforms - (including OS X). + (including macOS). </para> </listitem> @@ -943,10 +2207,10 @@ Branch: REL9_2_STABLE [37f30b251] 2016-04-18 13:19:52 -0400 <sect1 id="release-9-3-11"> <title>Release 9.3.11</title> - <note> - <title>Release Date</title> - <simpara>2016-02-11</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-02-11</para> + </formalpara> <para> This release contains a variety of fixes from 9.3.10. @@ -1566,10 +2830,10 @@ Branch: REL9_2_STABLE [37f30b251] 2016-04-18 13:19:52 -0400 <sect1 id="release-9-3-10"> <title>Release 9.3.10</title> - <note> - <title>Release Date</title> - <simpara>2015-10-08</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-10-08</para> + </formalpara> <para> This release contains a variety of fixes from 9.3.9. @@ -2195,10 +3459,10 @@ Branch: REL9_2_STABLE [37f30b251] 2016-04-18 13:19:52 -0400 <sect1 id="release-9-3-9"> <title>Release 9.3.9</title> - <note> - <title>Release Date</title> - <simpara>2015-06-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-06-12</para> + </formalpara> <para> This release contains a small number of fixes from 9.3.8. @@ -2344,10 +3608,10 @@ Branch: REL9_2_STABLE [37f30b251] 2016-04-18 13:19:52 -0400 <sect1 id="release-9-3-8"> <title>Release 9.3.8</title> - <note> - <title>Release Date</title> - <simpara>2015-06-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-06-04</para> + </formalpara> <para> This release contains a small number of fixes from 9.3.7. @@ -2452,10 +3716,10 @@ Branch: REL9_0_STABLE [4dddf8552] 2015-05-21 20:41:55 -0400 <sect1 id="release-9-3-7"> <title>Release 9.3.7</title> - <note> - <title>Release Date</title> - <simpara>2015-05-22</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-05-22</para> + </formalpara> <para> This release contains a variety of fixes from 9.3.6. @@ -3021,7 +4285,7 @@ Branch: REL9_0_STABLE [4dddf8552] 2015-05-21 20:41:55 -0400 <listitem> <para> - Silence some build warnings on OS X (Tom Lane) + Silence some build warnings on macOS (Tom Lane) </para> </listitem> @@ -3042,10 +4306,10 @@ Branch: REL9_0_STABLE [4dddf8552] 2015-05-21 20:41:55 -0400 <sect1 id="release-9-3-6"> <title>Release 9.3.6</title> - <note> - <title>Release Date</title> - <simpara>2015-02-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-02-05</para> + </formalpara> <para> This release contains a variety of fixes from 9.3.5. @@ -4092,7 +5356,7 @@ Branch: REL9_0_STABLE [2e4946169] 2015-01-07 22:46:20 -0500 <listitem> <para> - Warn if OS X's <function>setlocale()</> starts an unwanted extra + Warn if macOS's <function>setlocale()</> starts an unwanted extra thread inside the postmaster (Noah Misch) </para> </listitem> @@ -4927,10 +6191,10 @@ Branch: REL9_0_STABLE [b6391f587] 2014-10-04 14:18:43 -0400 <sect1 id="release-9-3-5"> <title>Release 9.3.5</title> - <note> - <title>Release Date</title> - <simpara>2014-07-24</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2014-07-24</para> + </formalpara> <para> This release contains a variety of fixes from 9.3.4. @@ -5743,7 +7007,7 @@ Branch: REL8_4_STABLE [ae41bb4be] 2014-05-30 18:18:32 -0400 <listitem> <para> - Fix linking of <application>libpython</> on OS X (Tom Lane) + Fix linking of <application>libpython</> on macOS (Tom Lane) </para> <para> @@ -6047,10 +7311,10 @@ Branch: REL8_4_STABLE [c51da696b] 2014-07-19 15:01:45 -0400 <sect1 id="release-9-3-4"> <title>Release 9.3.4</title> - <note> - <title>Release Date</title> - <simpara>2014-03-20</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2014-03-20</para> + </formalpara> <para> This release contains a variety of fixes from 9.3.3. @@ -6191,7 +7455,7 @@ Branch: REL8_4_STABLE [b6e143458] 2014-03-01 15:21:13 -0500 <para> This prevents scenarios wherein a pathological regular expression - could lock up a server process uninterruptably for a long time. + could lock up a server process uninterruptibly for a long time. </para> </listitem> @@ -6509,10 +7773,10 @@ Branch: REL8_4_STABLE [6e6c2c2e1] 2014-03-15 13:36:57 -0400 <sect1 id="release-9-3-3"> <title>Release 9.3.3</title> - <note> - <title>Release Date</title> - <simpara>2014-02-20</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2014-02-20</para> + </formalpara> <para> This release contains a variety of fixes from 9.3.2. @@ -7971,10 +9235,10 @@ Branch: REL8_4_STABLE [c0c2d62ac] 2014-02-14 21:59:56 -0500 <sect1 id="release-9-3-2"> <title>Release 9.3.2</title> - <note> - <title>Release Date</title> - <simpara>2013-12-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-12-05</para> + </formalpara> <para> This release contains a variety of fixes from 9.3.1. @@ -8450,10 +9714,10 @@ SELECT ... FROM tab1 x CROSS JOIN (tab2 x CROSS JOIN tab3 y) z <sect1 id="release-9-3-1"> <title>Release 9.3.1</title> - <note> - <title>Release Date</title> - <simpara>2013-10-10</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-10-10</para> + </formalpara> <para> This release contains a variety of fixes from 9.3.0. @@ -8553,10 +9817,10 @@ ALTER EXTENSION hstore UPDATE; <sect1 id="release-9-3"> <title>Release 9.3</title> - <note> - <title>Release Date</title> - <simpara>2013-09-09</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2013-09-09</para> + </formalpara> <sect2> <title>Overview</title> @@ -9303,7 +10567,7 @@ ALTER EXTENSION hstore UPDATE; <listitem> <para> Allow tools like <link - linkend="app-pgreceivexlog"><application>pg_receivexlog</></link> + linkend="app-pgreceivewal"><application>pg_receivexlog</></link> to run on computers with different architectures (Heikki Linnakangas) </para> @@ -9333,7 +10597,7 @@ ALTER EXTENSION hstore UPDATE; <listitem> <para> Allow <link - linkend="app-pgreceivexlog"><application>pg_receivexlog</></link> + linkend="app-pgreceivewal"><application>pg_receivexlog</></link> and <link linkend="app-pgbasebackup"><application>pg_basebackup</></link> <option>--xlog-method</> to handle streaming timeline switches @@ -9936,7 +11200,7 @@ ALTER EXTENSION hstore UPDATE; linkend="APP-PG-DUMPALL"><application>pg_dumpall</></link>, <link linkend="app-pgbasebackup"><application>pg_basebackup</></link>, and <link - linkend="app-pgreceivexlog"><application>pg_receivexlog</></link> + linkend="app-pgreceivewal"><application>pg_receivexlog</></link> to allow specifying a connection string (Amit Kapila) </para> </listitem> @@ -10473,7 +11737,7 @@ ALTER EXTENSION hstore UPDATE; <listitem> <para> - Add <link linkend="pgxlogdump"><application>pg_xlogdump</></link> + Add <link linkend="pgwaldump"><application>pg_xlogdump</></link> contrib program (Andres Freund) </para> </listitem> @@ -10710,7 +11974,7 @@ ALTER EXTENSION hstore UPDATE; <listitem> <para> Add <link linkend="docguide-toolsets">instructions</link> for setting - up the documentation tool chain on Mac <productname>OS X</> + up the documentation tool chain on <productname>macOS</> (Peter Eisentraut) </para> </listitem> diff --git a/doc/src/sgml/release-9.4.sgml b/doc/src/sgml/release-9.4.sgml index 443c772846..3317c11fc2 100644 --- a/doc/src/sgml/release-9.4.sgml +++ b/doc/src/sgml/release-9.4.sgml @@ -1,13 +1,1588 @@ <!-- doc/src/sgml/release-9.4.sgml --> <!-- See header comment in release.sgml about typical markup --> + <sect1 id="release-9-4-12"> + <title>Release 9.4.12</title> + + <formalpara> + <title>Release date:</title> + <para>2017-05-11</para> + </formalpara> + + <para> + This release contains a variety of fixes from 9.4.11. + For information about new features in the 9.4 major release, see + <xref linkend="release-9-4">. + </para> + + <sect2> + <title>Migration to Version 9.4.12</title> + + <para> + A dump/restore is not required for those running 9.4.X. + </para> + + <para> + However, if you use foreign data servers that make use of user + passwords for authentication, see the first changelog entry below. + </para> + + <para> + Also, if you are using third-party replication tools that depend + on <quote>logical decoding</>, see the fourth changelog entry below. + </para> + + <para> + Also, if you are upgrading from a version earlier than 9.4.11, + see <xref linkend="release-9-4-11">. + </para> + </sect2> + + <sect2> + <title>Changes</title> + + <itemizedlist> + + <listitem> + <para> + Restrict visibility + of <structname>pg_user_mappings</>.<structfield>umoptions</>, to + protect passwords stored as user mapping options + (Michael Paquier, Feike Steenbergen) + </para> + + <para> + The previous coding allowed the owner of a foreign server object, + or anyone he has granted server <literal>USAGE</> permission to, + to see the options for all user mappings associated with that server. + This might well include passwords for other users. + Adjust the view definition to match the behavior of + <structname>information_schema.user_mapping_options</>, namely that + these options are visible to the user being mapped, or if the mapping + is for <literal>PUBLIC</literal> and the current user is the server + owner, or if the current user is a superuser. + (CVE-2017-7486) + </para> + + <para> + By itself, this patch will only fix the behavior in newly initdb'd + databases. If you wish to apply this change in an existing database, + you will need to do the following: + </para> + + <procedure> + <step> + <para> + Restart the postmaster after adding <literal>allow_system_table_mods + = true</> to <filename>postgresql.conf</>. (In versions + supporting <command>ALTER SYSTEM</>, you can use that to make the + configuration change, but you'll still need a restart.) + </para> + </step> + + <step> + <para> + In <emphasis>each</> database of the cluster, + run the following commands as superuser: +<programlisting> +SET search_path = pg_catalog; +CREATE OR REPLACE VIEW pg_user_mappings AS + SELECT + U.oid AS umid, + S.oid AS srvid, + S.srvname AS srvname, + U.umuser AS umuser, + CASE WHEN U.umuser = 0 THEN + 'public' + ELSE + A.rolname + END AS usename, + CASE WHEN (U.umuser <> 0 AND A.rolname = current_user) + OR (U.umuser = 0 AND pg_has_role(S.srvowner, 'USAGE')) + OR (SELECT rolsuper FROM pg_authid WHERE rolname = current_user) + THEN U.umoptions + ELSE NULL END AS umoptions + FROM pg_user_mapping U + LEFT JOIN pg_authid A ON (A.oid = U.umuser) JOIN + pg_foreign_server S ON (U.umserver = S.oid); +</programlisting> + </para> + </step> + + <step> + <para> + Do not forget to include the <literal>template0</> + and <literal>template1</> databases, or the vulnerability will still + exist in databases you create later. To fix <literal>template0</>, + you'll need to temporarily make it accept connections. + In <productname>PostgreSQL</> 9.5 and later, you can use +<programlisting> +ALTER DATABASE template0 WITH ALLOW_CONNECTIONS true; +</programlisting> + and then after fixing <literal>template0</>, undo that with +<programlisting> +ALTER DATABASE template0 WITH ALLOW_CONNECTIONS false; +</programlisting> + In prior versions, instead use +<programlisting> +UPDATE pg_database SET datallowconn = true WHERE datname = 'template0'; +UPDATE pg_database SET datallowconn = false WHERE datname = 'template0'; +</programlisting> + </para> + </step> + + <step> + <para> + Finally, remove the <literal>allow_system_table_mods</> configuration + setting, and again restart the postmaster. + </para> + </step> + </procedure> + </listitem> + + <listitem> + <para> + Prevent exposure of statistical information via leaky operators + (Peter Eisentraut) + </para> + + <para> + Some selectivity estimation functions in the planner will apply + user-defined operators to values obtained + from <structname>pg_statistic</>, such as most common values and + histogram entries. This occurs before table permissions are checked, + so a nefarious user could exploit the behavior to obtain these values + for table columns he does not have permission to read. To fix, + fall back to a default estimate if the operator's implementation + function is not certified leak-proof and the calling user does not have + permission to read the table column whose statistics are needed. + At least one of these criteria is satisfied in most cases in practice. + (CVE-2017-7484) + </para> + </listitem> + + <listitem> + <para> + Restore <application>libpq</>'s recognition of + the <envar>PGREQUIRESSL</> environment variable (Daniel Gustafsson) + </para> + + <para> + Processing of this environment variable was unintentionally dropped + in <productname>PostgreSQL</> 9.3, but its documentation remained. + This creates a security hazard, since users might be relying on the + environment variable to force SSL-encrypted connections, but that + would no longer be guaranteed. Restore handling of the variable, + but give it lower priority than <envar>PGSSLMODE</>, to avoid + breaking configurations that work correctly with post-9.3 code. + (CVE-2017-7485) + </para> + </listitem> + + <listitem> + <para> + Fix possibly-invalid initial snapshot during logical decoding + (Petr Jelinek, Andres Freund) + </para> + + <para> + The initial snapshot created for a logical decoding replication slot + was potentially incorrect. This could cause third-party tools that + use logical decoding to copy incomplete/inconsistent initial data. + This was more likely to happen if the source server was busy at the + time of slot creation, or if another logical slot already existed. + </para> + + <para> + If you are using a replication tool that depends on logical decoding, + and it should have copied a nonempty data set at the start of + replication, it is advisable to recreate the replica after + installing this update, or to verify its contents against the source + server. + </para> + </listitem> + + <listitem> + <para> + Fix possible corruption of <quote>init forks</> of unlogged indexes + (Robert Haas, Michael Paquier) + </para> + + <para> + This could result in an unlogged index being set to an invalid state + after a crash and restart. Such a problem would persist until the + index was dropped and rebuilt. + </para> + </listitem> + + <listitem> + <para> + Fix incorrect reconstruction of <structname>pg_subtrans</> entries + when a standby server replays a prepared but uncommitted two-phase + transaction (Tom Lane) + </para> + + <para> + In most cases this turned out to have no visible ill effects, but in + corner cases it could result in circular references + in <structname>pg_subtrans</>, potentially causing infinite loops + in queries that examine rows modified by the two-phase transaction. + </para> + </listitem> + + <listitem> + <para> + Avoid possible crash in <application>walsender</> due to failure + to initialize a string buffer (Stas Kelvich, Fujii Masao) + </para> + </listitem> + + <listitem> + <para> + Fix postmaster's handling of <function>fork()</> failure for a + background worker process (Tom Lane) + </para> + + <para> + Previously, the postmaster updated portions of its state as though + the process had been launched successfully, resulting in subsequent + confusion. + </para> + </listitem> + + <listitem> + <para> + Ensure parsing of queries in extension scripts sees the results of + immediately-preceding DDL (Julien Rouhaud, Tom Lane) + </para> + + <para> + Due to lack of a cache flush step between commands in an extension + script file, non-utility queries might not see the effects of an + immediately preceding catalog change, such as <command>ALTER TABLE + ... RENAME</>. + </para> + </listitem> + + <listitem> + <para> + Skip tablespace privilege checks when <command>ALTER TABLE ... ALTER + COLUMN TYPE</> rebuilds an existing index (Noah Misch) + </para> + + <para> + The command failed if the calling user did not currently have + <literal>CREATE</> privilege for the tablespace containing the index. + That behavior seems unhelpful, so skip the check, allowing the + index to be rebuilt where it is. + </para> + </listitem> + + <listitem> + <para> + Fix <command>ALTER TABLE ... VALIDATE CONSTRAINT</> to not recurse + to child tables when the constraint is marked <literal>NO INHERIT</> + (Amit Langote) + </para> + + <para> + This fix prevents unwanted <quote>constraint does not exist</> failures + when no matching constraint is present in the child tables. + </para> + </listitem> + + <listitem> + <para> + Fix <command>VACUUM</> to account properly for pages that could not + be scanned due to conflicting page pins (Andrew Gierth) + </para> + + <para> + This tended to lead to underestimation of the number of tuples in + the table. In the worst case of a small heavily-contended + table, <command>VACUUM</> could incorrectly report that the table + contained no tuples, leading to very bad planning choices. + </para> + </listitem> + + <listitem> + <para> + Ensure that bulk-tuple-transfer loops within a hash join are + interruptible by query cancel requests (Tom Lane, Thomas Munro) + </para> + </listitem> + + <listitem> + <para> + Fix integer-overflow problems in <type>interval</> comparison (Kyotaro + Horiguchi, Tom Lane) + </para> + + <para> + The comparison operators for type <type>interval</> could yield wrong + answers for intervals larger than about 296000 years. Indexes on + columns containing such large values should be reindexed, since they + may be corrupt. + </para> + </listitem> + + <listitem> + <para> + Fix <function>cursor_to_xml()</> to produce valid output + with <replaceable>tableforest</> = false + (Thomas Munro, Peter Eisentraut) + </para> + + <para> + Previously it failed to produce a wrapping <literal><table></> + element. + </para> + </listitem> + + <listitem> + <para> + Fix roundoff problems in <function>float8_timestamptz()</> + and <function>make_interval()</> (Tom Lane) + </para> + + <para> + These functions truncated, rather than rounded, when converting a + floating-point value to integer microseconds; that could cause + unexpectedly off-by-one results. + </para> + </listitem> + + <listitem> + <para> + Improve performance of <structname>pg_timezone_names</> view + (Tom Lane, David Rowley) + </para> + </listitem> + + <listitem> + <para> + Reduce memory management overhead for contexts containing many large + blocks (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix sloppy handling of corner-case errors from <function>lseek()</> + and <function>close()</> (Tom Lane) + </para> + + <para> + Neither of these system calls are likely to fail in typical situations, + but if they did, <filename>fd.c</> could get quite confused. + </para> + </listitem> + + <listitem> + <para> + Fix incorrect check for whether postmaster is running as a Windows + service (Michael Paquier) + </para> + + <para> + This could result in attempting to write to the event log when that + isn't accessible, so that no logging happens at all. + </para> + </listitem> + + <listitem> + <para> + Fix <application>ecpg</> to support <command>COMMIT PREPARED</> + and <command>ROLLBACK PREPARED</> (Masahiko Sawada) + </para> + </listitem> + + <listitem> + <para> + Fix a double-free error when processing dollar-quoted string literals + in <application>ecpg</> (Michael Meskes) + </para> + </listitem> + + <listitem> + <para> + In <application>pg_dump</>, fix incorrect schema and owner marking for + comments and security labels of some types of database objects + (Giuseppe Broccolo, Tom Lane) + </para> + + <para> + In simple cases this caused no ill effects; but for example, a + schema-selective restore might omit comments it should include, because + they were not marked as belonging to the schema of their associated + object. + </para> + </listitem> + + <listitem> + <para> + Avoid emitting an invalid list file in <literal>pg_restore -l</> + when SQL object names contain newlines (Tom Lane) + </para> + + <para> + Replace newlines by spaces, which is sufficient to make the output + valid for <literal>pg_restore -L</>'s purposes. + </para> + </listitem> + + <listitem> + <para> + Fix <application>pg_upgrade</> to transfer comments and security labels + attached to <quote>large objects</> (blobs) (Stephen Frost) + </para> + + <para> + Previously, blobs were correctly transferred to the new database, but + any comments or security labels attached to them were lost. + </para> + </listitem> + + <listitem> + <para> + Improve error handling + in <filename>contrib/adminpack</>'s <function>pg_file_write()</> + function (Noah Misch) + </para> + + <para> + Notably, it failed to detect errors reported + by <function>fclose()</>. + </para> + </listitem> + + <listitem> + <para> + In <filename>contrib/dblink</>, avoid leaking the previous unnamed + connection when establishing a new unnamed connection (Joe Conway) + </para> + </listitem> + + <listitem> + <para> + Fix <filename>contrib/pg_trgm</>'s extraction of trigrams from regular + expressions (Tom Lane) + </para> + + <para> + In some cases it would produce a broken data structure that could never + match anything, leading to GIN or GiST indexscans that use a trigram + index not finding any matches to the regular expression. + </para> + </listitem> + + <listitem> + <para> + In <filename>contrib/postgres_fdw</>, + transmit query cancellation requests to the remote server + (Michael Paquier, Etsuro Fujita) + </para> + + <para> + Previously, a local query cancellation request did not cause an + already-sent remote query to terminate early. This is a back-patch + of work originally done for 9.6. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: REL9_4_STABLE [bb132cddf] 2017-04-15 20:16:03 -0400 +Branch: REL9_3_STABLE [fbfeceb25] 2017-04-17 12:51:40 -0400 +Branch: REL9_2_STABLE [58384149b] 2017-04-17 12:51:40 -0400 +Branch: REL9_3_STABLE [4e91330da] 2017-04-17 13:52:42 -0400 +Branch: REL9_2_STABLE [fb50c38e9] 2017-04-17 13:52:42 -0400 +--> + <para> + Support OpenSSL 1.1.0 (Heikki Linnakangas, Andreas Karlsson, Tom Lane) + </para> + + <para> + This is a back-patch of work previously done in newer branches; + it's needed since many platforms are adopting newer OpenSSL versions. + </para> + </listitem> + + <listitem> + <para> + Support Tcl 8.6 in MSVC builds (Álvaro Herrera) + </para> + </listitem> + + <listitem> + <para> + Sync our copy of the timezone library with IANA release tzcode2017b + (Tom Lane) + </para> + + <para> + This fixes a bug affecting some DST transitions in January 2038. + </para> + </listitem> + + <listitem> + <para> + Update time zone data files to <application>tzdata</> release 2017b + for DST law changes in Chile, Haiti, and Mongolia, plus historical + corrections for Ecuador, Kazakhstan, Liberia, and Spain. + Switch to numeric abbreviations for numerous time zones in South + America, the Pacific and Indian oceans, and some Asian and Middle + Eastern countries. + </para> + + <para> + The IANA time zone database previously provided textual abbreviations + for all time zones, sometimes making up abbreviations that have little + or no currency among the local population. They are in process of + reversing that policy in favor of using numeric UTC offsets in zones + where there is no evidence of real-world use of an English + abbreviation. At least for the time being, <productname>PostgreSQL</> + will continue to accept such removed abbreviations for timestamp input. + But they will not be shown in the <structname>pg_timezone_names</> + view nor used for output. + </para> + </listitem> + + <listitem> + <para> + Use correct daylight-savings rules for POSIX-style time zone names + in MSVC builds (David Rowley) + </para> + + <para> + The Microsoft MSVC build scripts neglected to install + the <filename>posixrules</> file in the timezone directory tree. + This resulted in the timezone code falling back to its built-in + rule about what DST behavior to assume for a POSIX-style time zone + name. For historical reasons that still corresponds to the DST rules + the USA was using before 2007 (i.e., change on first Sunday in April + and last Sunday in October). With this fix, a POSIX-style zone name + will use the current and historical DST transition dates of + the <literal>US/Eastern</> zone. If you don't want that, remove + the <filename>posixrules</> file, or replace it with a copy of some + other zone file (see <xref linkend="datatype-timezones">). Note that + due to caching, you may need to restart the server to get such changes + to take effect. + </para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + + <sect1 id="release-9-4-11"> + <title>Release 9.4.11</title> + + <formalpara> + <title>Release date:</title> + <para>2017-02-09</para> + </formalpara> + + <para> + This release contains a variety of fixes from 9.4.10. + For information about new features in the 9.4 major release, see + <xref linkend="release-9-4">. + </para> + + <sect2> + <title>Migration to Version 9.4.11</title> + + <para> + A dump/restore is not required for those running 9.4.X. + </para> + + <para> + However, if your installation has been affected by the bug described in + the first changelog entry below, then after updating you may need + to take action to repair corrupted indexes. + </para> + + <para> + Also, if you are upgrading from a version earlier than 9.4.10, + see <xref linkend="release-9-4-10">. + </para> + </sect2> + + <sect2> + <title>Changes</title> + + <itemizedlist> + + <listitem> + <para> + Fix a race condition that could cause indexes built + with <command>CREATE INDEX CONCURRENTLY</> to be corrupt + (Pavan Deolasee, Tom Lane) + </para> + + <para> + If <command>CREATE INDEX CONCURRENTLY</> was used to build an index + that depends on a column not previously indexed, then rows + updated by transactions that ran concurrently with + the <command>CREATE INDEX</> command could have received incorrect + index entries. If you suspect this may have happened, the most + reliable solution is to rebuild affected indexes after installing + this update. + </para> + </listitem> + + <listitem> + <para> + Ensure that the special snapshot used for catalog scans is not + invalidated by premature data pruning (Tom Lane) + </para> + + <para> + Backends failed to account for this snapshot when advertising their + oldest xmin, potentially allowing concurrent vacuuming operations to + remove data that was still needed. This led to transient failures + along the lines of <quote>cache lookup failed for relation 1255</>. + </para> + </listitem> + + <listitem> + <para> + Unconditionally WAL-log creation of the <quote>init fork</> for an + unlogged table (Michael Paquier) + </para> + + <para> + Previously, this was skipped when <xref linkend="guc-wal-level"> + = <literal>minimal</>, but actually it's necessary even in that case + to ensure that the unlogged table is properly reset to empty after a + crash. + </para> + </listitem> + + <listitem> + <para> + Reduce interlocking on standby servers during the replay of btree + index vacuuming operations (Simon Riggs) + </para> + + <para> + This change avoids substantial replication delays that sometimes + occurred while replaying such operations. + </para> + </listitem> + + <listitem> + <para> + If the stats collector dies during hot standby, restart it (Takayuki + Tsunakawa) + </para> + </listitem> + + <listitem> + <para> + Ensure that hot standby feedback works correctly when it's enabled at + standby server start (Ants Aasma, Craig Ringer) + </para> + </listitem> + + <listitem> + <para> + Check for interrupts while hot standby is waiting for a conflicting + query (Simon Riggs) + </para> + </listitem> + + <listitem> + <para> + Avoid constantly respawning the autovacuum launcher in a corner case + (Amit Khandekar) + </para> + + <para> + This fix avoids problems when autovacuum is nominally off and there + are some tables that require freezing, but all such tables are + already being processed by autovacuum workers. + </para> + </listitem> + + <listitem> + <para> + Fix check for when an extension member object can be dropped (Tom Lane) + </para> + + <para> + Extension upgrade scripts should be able to drop member objects, + but this was disallowed for serial-column sequences, and possibly + other cases. + </para> + </listitem> + + <listitem> + <para> + Make sure <command>ALTER TABLE</> preserves index tablespace + assignments when rebuilding indexes (Tom Lane, Michael Paquier) + </para> + + <para> + Previously, non-default settings + of <xref linkend="guc-default-tablespace"> could result in broken + indexes. + </para> + </listitem> + + <listitem> + <para> + Fix incorrect updating of trigger function properties when changing a + foreign-key constraint's deferrability properties with <command>ALTER + TABLE ... ALTER CONSTRAINT</> (Tom Lane) + </para> + + <para> + This led to odd failures during subsequent exercise of the foreign + key, as the triggers were fired at the wrong times. + </para> + </listitem> + + <listitem> + <para> + Prevent dropping a foreign-key constraint if there are pending + trigger events for the referenced relation (Tom Lane) + </para> + + <para> + This avoids <quote>could not find trigger <replaceable>NNN</></quote> + or <quote>relation <replaceable>NNN</> has no triggers</quote> errors. + </para> + </listitem> + + <listitem> + <para> + Fix processing of OID column when a table with OIDs is associated to + a parent with OIDs via <command>ALTER TABLE ... INHERIT</> (Amit + Langote) + </para> + + <para> + The OID column should be treated the same as regular user columns in + this case, but it wasn't, leading to odd behavior in later + inheritance changes. + </para> + </listitem> + + <listitem> + <para> + Fix <command>CREATE OR REPLACE VIEW</> to update the view query + before attempting to apply the new view options (Dean Rasheed) + </para> + + <para> + Previously the command would fail if the new options were + inconsistent with the old view definition. + </para> + </listitem> + + <listitem> + <para> + Report correct object identity during <command>ALTER TEXT SEARCH + CONFIGURATION</> (Artur Zakirov) + </para> + + <para> + The wrong catalog OID was reported to extensions such as logical + decoding. + </para> + </listitem> + + <listitem> + <para> + Check for serializability conflicts before reporting + constraint-violation failures (Thomas Munro) + </para> + + <para> + When using serializable transaction isolation, it is desirable + that any error due to concurrent transactions should manifest + as a serialization failure, thereby cueing the application that + a retry might succeed. Unfortunately, this does not reliably + happen for duplicate-key failures caused by concurrent insertions. + This change ensures that such an error will be reported as a + serialization error if the application explicitly checked for + the presence of a conflicting key (and did not find it) earlier + in the transaction. + </para> + </listitem> + + <listitem> + <para> + Prevent multicolumn expansion of <replaceable>foo</><literal>.*</> in + an <command>UPDATE</> source expression (Tom Lane) + </para> + + <para> + This led to <quote>UPDATE target count mismatch --- internal + error</>. Now the syntax is understood as a whole-row variable, + as it would be in other contexts. + </para> + </listitem> + + <listitem> + <para> + Ensure that column typmods are determined accurately for + multi-row <literal>VALUES</> constructs (Tom Lane) + </para> + + <para> + This fixes problems occurring when the first value in a column has a + determinable typmod (e.g., length for a <type>varchar</> value) but + later values don't share the same limit. + </para> + </listitem> + + <listitem> + <para> + Throw error for an unfinished Unicode surrogate pair at the end of a + Unicode string (Tom Lane) + </para> + + <para> + Normally, a Unicode surrogate leading character must be followed by a + Unicode surrogate trailing character, but the check for this was + missed if the leading character was the last character in a Unicode + string literal (<literal>U&'...'</>) or Unicode identifier + (<literal>U&"..."</>). + </para> + </listitem> + + <listitem> + <para> + Ensure that a purely negative text search query, such + as <literal>!foo</>, matches empty <type>tsvector</>s (Tom Dunstan) + </para> + + <para> + Such matches were found by GIN index searches, but not by sequential + scans or GiST index searches. + </para> + </listitem> + + <listitem> + <para> + Prevent crash when <function>ts_rewrite()</> replaces a non-top-level + subtree with an empty query (Artur Zakirov) + </para> + </listitem> + + <listitem> + <para> + Fix performance problems in <function>ts_rewrite()</> (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix <function>ts_rewrite()</>'s handling of nested NOT operators + (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix <function>array_fill()</> to handle empty arrays properly (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix one-byte buffer overrun in <function>quote_literal_cstr()</> + (Heikki Linnakangas) + </para> + + <para> + The overrun occurred only if the input consisted entirely of single + quotes and/or backslashes. + </para> + </listitem> + + <listitem> + <para> + Prevent multiple calls of <function>pg_start_backup()</> + and <function>pg_stop_backup()</> from running concurrently (Michael + Paquier) + </para> + + <para> + This avoids an assertion failure, and possibly worse things, if + someone tries to run these functions in parallel. + </para> + </listitem> + + <listitem> + <para> + Avoid discarding <type>interval</>-to-<type>interval</> casts + that aren't really no-ops (Tom Lane) + </para> + + <para> + In some cases, a cast that should result in zeroing out + low-order <type>interval</> fields was mistakenly deemed to be a + no-op and discarded. An example is that casting from <type>INTERVAL + MONTH</> to <type>INTERVAL YEAR</> failed to clear the months field. + </para> + </listitem> + + <listitem> + <para> + Ensure that cached plans are invalidated by changes in foreign-table + options (Amit Langote, Etsuro Fujita, Ashutosh Bapat) + </para> + </listitem> + + <listitem> + <para> + Fix <application>pg_dump</> to dump user-defined casts and transforms + that use built-in functions (Stephen Frost) + </para> + </listitem> + + <listitem> + <para> + Fix <application>pg_restore</> with <option>--create --if-exists</> + to behave more sanely if an archive contains + unrecognized <command>DROP</> commands (Tom Lane) + </para> + + <para> + This doesn't fix any live bug, but it may improve the behavior in + future if <application>pg_restore</> is used with an archive + generated by a later <application>pg_dump</> version. + </para> + </listitem> + + <listitem> + <para> + Fix <application>pg_basebackup</>'s rate limiting in the presence of + slow I/O (Antonin Houska) + </para> + + <para> + If disk I/O was transiently much slower than the specified rate + limit, the calculation overflowed, effectively disabling the rate + limit for the rest of the run. + </para> + </listitem> + + <listitem> + <para> + Fix <application>pg_basebackup</>'s handling of + symlinked <filename>pg_stat_tmp</> and <filename>pg_replslot</> + subdirectories (Magnus Hagander, Michael Paquier) + </para> + </listitem> + + <listitem> + <para> + Fix possible <application>pg_basebackup</> failure on standby + server when including WAL files (Amit Kapila, Robert Haas) + </para> + </listitem> + + <listitem> + <para> + Ensure that the Python exception objects we create for PL/Python are + properly reference-counted (Rafa de la Torre, Tom Lane) + </para> + + <para> + This avoids failures if the objects are used after a Python garbage + collection cycle has occurred. + </para> + </listitem> + + <listitem> + <para> + Fix PL/Tcl to support triggers on tables that have <literal>.tupno</> + as a column name (Tom Lane) + </para> + + <para> + This matches the (previously undocumented) behavior of + PL/Tcl's <command>spi_exec</> and <command>spi_execp</> commands, + namely that a magic <literal>.tupno</> column is inserted only if + there isn't a real column named that. + </para> + </listitem> + + <listitem> + <para> + Allow DOS-style line endings in <filename>~/.pgpass</> files, + even on Unix (Vik Fearing) + </para> + + <para> + This change simplifies use of the same password file across Unix and + Windows machines. + </para> + </listitem> + + <listitem> + <para> + Fix one-byte buffer overrun if <application>ecpg</> is given a file + name that ends with a dot (Takayuki Tsunakawa) + </para> + </listitem> + + <listitem> + <para> + Fix <application>psql</>'s tab completion for <command>ALTER DEFAULT + PRIVILEGES</> (Gilles Darold, Stephen Frost) + </para> + </listitem> + + <listitem> + <para> + In <application>psql</>, treat an empty or all-blank setting of + the <envar>PAGER</> environment variable as meaning <quote>no + pager</> (Tom Lane) + </para> + + <para> + Previously, such a setting caused output intended for the pager to + vanish entirely. + </para> + </listitem> + + <listitem> + <para> + Improve <filename>contrib/dblink</>'s reporting of + low-level <application>libpq</> errors, such as out-of-memory + (Joe Conway) + </para> + </listitem> + + <listitem> + <para> + Teach <filename>contrib/dblink</> to ignore irrelevant server options + when it uses a <filename>contrib/postgres_fdw</> foreign server as + the source of connection options (Corey Huinker) + </para> + + <para> + Previously, if the foreign server object had options that were not + also <application>libpq</> connection options, an error occurred. + </para> + </listitem> + + <listitem> + <para> + On Windows, ensure that environment variable changes are propagated + to DLLs built with debug options (Christian Ullrich) + </para> + </listitem> + + <listitem> + <para> + Sync our copy of the timezone library with IANA release tzcode2016j + (Tom Lane) + </para> + + <para> + This fixes various issues, most notably that timezone data + installation failed if the target directory didn't support hard + links. + </para> + </listitem> + + <listitem> + <para> + Update time zone data files to <application>tzdata</> release 2016j + for DST law changes in northern Cyprus (adding a new zone + Asia/Famagusta), Russia (adding a new zone Europe/Saratov), Tonga, + and Antarctica/Casey. + Historical corrections for Italy, Kazakhstan, Malta, and Palestine. + Switch to preferring numeric zone abbreviations for Tonga. + </para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + + <sect1 id="release-9-4-10"> + <title>Release 9.4.10</title> + + <formalpara> + <title>Release date:</title> + <para>2016-10-27</para> + </formalpara> + + <para> + This release contains a variety of fixes from 9.4.9. + For information about new features in the 9.4 major release, see + <xref linkend="release-9-4">. + </para> + + <sect2> + <title>Migration to Version 9.4.10</title> + + <para> + A dump/restore is not required for those running 9.4.X. + </para> + + <para> + However, if your installation has been affected by the bug described in + the first changelog entry below, then after updating you may need + to take action to repair corrupted free space maps. + </para> + + <para> + Also, if you are upgrading from a version earlier than 9.4.6, + see <xref linkend="release-9-4-6">. + </para> + </sect2> + + <sect2> + <title>Changes</title> + + <itemizedlist> + + <listitem> + <para> + Fix WAL-logging of truncation of relation free space maps and + visibility maps (Pavan Deolasee, Heikki Linnakangas) + </para> + + <para> + It was possible for these files to not be correctly restored during + crash recovery, or to be written incorrectly on a standby server. + Bogus entries in a free space map could lead to attempts to access + pages that have been truncated away from the relation itself, typically + producing errors like <quote>could not read block <replaceable>XXX</>: + read only 0 of 8192 bytes</quote>. Checksum failures in the + visibility map are also possible, if checksumming is enabled. + </para> + + <para> + Procedures for determining whether there is a problem and repairing it + if so are discussed at + <ulink url="https://wiki.postgresql.org/wiki/Free_Space_Map_Problems"></>. + </para> + </listitem> + + <listitem> + <para> + Fix incorrect creation of GIN index WAL records on big-endian machines + (Tom Lane) + </para> + + <para> + The typical symptom was <quote>unexpected GIN leaf action</> errors + during WAL replay. + </para> + </listitem> + + <listitem> + <para> + Fix <command>SELECT FOR UPDATE/SHARE</> to correctly lock tuples that + have been updated by a subsequently-aborted transaction + (Álvaro Herrera) + </para> + + <para> + In 9.5 and later, the <command>SELECT</> would sometimes fail to + return such tuples at all. A failure has not been proven to occur in + earlier releases, but might be possible with concurrent updates. + </para> + </listitem> + + <listitem> + <para> + Fix EvalPlanQual rechecks involving CTE scans (Tom Lane) + </para> + + <para> + The recheck would always see the CTE as returning no rows, typically + leading to failure to update rows that were recently updated. + </para> + </listitem> + + <listitem> + <para> + Fix improper repetition of previous results from hashed aggregation in + a subquery (Andrew Gierth) + </para> + + <para> + The test to see if we can reuse a previously-computed hash table of + the aggregate state values neglected the possibility of an outer query + reference appearing in an aggregate argument expression. A change in + the value of such a reference should lead to recalculating the hash + table, but did not. + </para> + </listitem> + + <listitem> + <para> + Fix query-lifespan memory leak in a bulk <command>UPDATE</> on a table + with a <literal>PRIMARY KEY</> or <literal>REPLICA IDENTITY</> index + (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix <command>EXPLAIN</> to emit valid XML when + <xref linkend="guc-track-io-timing"> is on (Markus Winand) + </para> + + <para> + Previously the XML output-format option produced syntactically invalid + tags such as <literal><I/O-Read-Time></>. That is now + rendered as <literal><I-O-Read-Time></>. + </para> + </listitem> + + <listitem> + <para> + Suppress printing of zeroes for unmeasured times + in <command>EXPLAIN</> (Maksim Milyutin) + </para> + + <para> + Certain option combinations resulted in printing zero values for times + that actually aren't ever measured in that combination. Our general + policy in <command>EXPLAIN</> is not to print such fields at all, so + do that consistently in all cases. + </para> + </listitem> + + <listitem> + <para> + Fix timeout length when <command>VACUUM</> is waiting for exclusive + table lock so that it can truncate the table (Simon Riggs) + </para> + + <para> + The timeout was meant to be 50 milliseconds, but it was actually only + 50 microseconds, causing <command>VACUUM</> to give up on truncation + much more easily than intended. Set it to the intended value. + </para> + </listitem> + + <listitem> + <para> + Fix bugs in merging inherited <literal>CHECK</> constraints while + creating or altering a table (Tom Lane, Amit Langote) + </para> + + <para> + Allow identical <literal>CHECK</> constraints to be added to a parent + and child table in either order. Prevent merging of a valid + constraint from the parent table with a <literal>NOT VALID</> + constraint on the child. Likewise, prevent merging of a <literal>NO + INHERIT</> child constraint with an inherited constraint. + </para> + </listitem> + + <listitem> + <para> + Remove artificial restrictions on the values accepted + by <function>numeric_in()</> and <function>numeric_recv()</> + (Tom Lane) + </para> + + <para> + We allow numeric values up to the limit of the storage format (more + than <literal>1e100000</>), so it seems fairly pointless + that <function>numeric_in()</> rejected scientific-notation exponents + above 1000. Likewise, it was silly for <function>numeric_recv()</> to + reject more than 1000 digits in an input value. + </para> + </listitem> + + <listitem> + <para> + Avoid very-low-probability data corruption due to testing tuple + visibility without holding buffer lock (Thomas Munro, Peter Geoghegan, + Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix logical WAL decoding to work properly when a subtransaction's WAL + output is large enough to spill to disk (Andres Freund) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: REL9_4_STABLE [10ad15f48] 2016-09-01 11:45:16 -0400 +--> + <para> + Fix buffer overread in logical WAL decoding (Tom Lane) + </para> + + <para> + Logical decoding of a tuple update record read 23 bytes too many, + which was usually harmless but with very bad luck could result in a + crash. + </para> + </listitem> + + <listitem> + <para> + Fix file descriptor leakage when truncating a temporary relation of + more than 1GB (Andres Freund) + </para> + </listitem> + + <listitem> + <para> + Disallow starting a standalone backend with <literal>standby_mode</> + turned on (Michael Paquier) + </para> + + <para> + This can't do anything useful, since there will be no WAL receiver + process to fetch more WAL data; and it could result in misbehavior + in code that wasn't designed with this situation in mind. + </para> + </listitem> + + <listitem> + <para> + Properly initialize replication slot state when recycling a + previously-used slot (Michael Paquier) + </para> + + <para> + This failure to reset all of the fields of the slot could + prevent <command>VACUUM</> from removing dead tuples. + </para> + </listitem> + + <listitem> + <para> + Round shared-memory allocation request to a multiple of the actual + huge page size when attempting to use huge pages on Linux (Tom Lane) + </para> + + <para> + This avoids possible failures during <function>munmap()</> on systems + with atypical default huge page sizes. Except in crash-recovery + cases, there were no ill effects other than a log message. + </para> + </listitem> + + <listitem> + <para> + Use a more random value for the dynamic shared memory control + segment's ID (Robert Haas, Tom Lane) + </para> + + <para> + Previously, the same value would be chosen every time, because it was + derived from <function>random()</> but <function>srandom()</> had not + yet been called. While relatively harmless, this was not the intended + behavior. + </para> + </listitem> + + <listitem> + <para> + On Windows, retry creation of the dynamic shared memory control + segment after an access-denied error (Kyotaro Horiguchi, Amit Kapila) + </para> + + <para> + Windows sometimes returns <literal>ERROR_ACCESS_DENIED</> rather + than <literal>ERROR_ALREADY_EXISTS</> when there is an existing + segment. This led to postmaster startup failure due to believing that + the former was an unrecoverable error. + </para> + </listitem> + + <listitem> + <para> + Don't try to share SSL contexts across multiple connections + in <application>libpq</> (Heikki Linnakangas) + </para> + + <para> + This led to assorted corner-case bugs, particularly when trying to use + different SSL parameters for different connections. + </para> + </listitem> + + <listitem> + <para> + Avoid corner-case memory leak in <application>libpq</> (Tom Lane) + </para> + + <para> + The reported problem involved leaking an error report + during <function>PQreset()</>, but there might be related cases. + </para> + </listitem> + + <listitem> + <para> + Make <application>ecpg</>'s <option>--help</> and <option>--version</> + options work consistently with our other executables (Haribabu Kommi) + </para> + </listitem> + + <listitem> + <para> + Fix <application>pgbench</>'s calculation of average latency + (Fabien Coelho) + </para> + + <para> + The calculation was incorrect when there were <literal>\sleep</> + commands in the script, or when the test duration was specified in + number of transactions rather than total time. + </para> + </listitem> + + <listitem> + <para> + In <application>pg_dump</>, never dump range constructor functions + (Tom Lane) + </para> + + <para> + This oversight led to <application>pg_upgrade</> failures with + extensions containing range types, due to duplicate creation of the + constructor functions. + </para> + </listitem> + + <listitem> + <para> + In <application>pg_xlogdump</>, retry opening new WAL segments when + using <option>--follow</> option (Magnus Hagander) + </para> + + <para> + This allows for a possible delay in the server's creation of the next + segment. + </para> + </listitem> + + <listitem> + <para> + Fix <application>pg_xlogdump</> to cope with a WAL file that begins + with a continuation record spanning more than one page (Pavan + Deolasee) + </para> + </listitem> + + <listitem> + <para> + Fix <filename>contrib/pg_buffercache</> to work + when <varname>shared_buffers</> exceeds 256GB (KaiGai Kohei) + </para> + </listitem> + + <listitem> + <para> + Fix <filename>contrib/intarray/bench/bench.pl</> to print the results + of the <command>EXPLAIN</> it does when given the <option>-e</> option + (Daniel Gustafsson) + </para> + </listitem> + + <listitem> + <para> + Install TAP test infrastructure so that it's available for extension + testing (Craig Ringer) + </para> + + <para> + When <productname>PostgreSQL</> has been configured + with <option>--enable-tap-tests</>, <quote>make install</> will now + install the Perl support files for TAP testing where PGXS can find + them. This allows non-core extensions to + use <literal>$(prove_check)</> without extra tests. + </para> + </listitem> + + <listitem> + <para> + In MSVC builds, include <application>pg_recvlogical</> in a + client-only installation (MauMau) + </para> + </listitem> + + <listitem> + <para> + Update Windows time zone mapping to recognize some time zone names + added in recent Windows versions (Michael Paquier) + </para> + </listitem> + + <listitem> + <para> + Prevent failure of obsolete dynamic time zone abbreviations (Tom Lane) + </para> + + <para> + If a dynamic time zone abbreviation does not match any entry in the + referenced time zone, treat it as equivalent to the time zone name. + This avoids unexpected failures when IANA removes abbreviations from + their time zone database, as they did in <application>tzdata</> + release 2016f and seem likely to do again in the future. The + consequences were not limited to not recognizing the individual + abbreviation; any mismatch caused + the <structname>pg_timezone_abbrevs</> view to fail altogether. + </para> + </listitem> + + <listitem> + <para> + Update time zone data files to <application>tzdata</> release 2016h + for DST law changes in Palestine and Turkey, plus historical + corrections for Turkey and some regions of Russia. + Switch to numeric abbreviations for some time zones in Antarctica, + the former Soviet Union, and Sri Lanka. + </para> + + <para> + The IANA time zone database previously provided textual abbreviations + for all time zones, sometimes making up abbreviations that have little + or no currency among the local population. They are in process of + reversing that policy in favor of using numeric UTC offsets in zones + where there is no evidence of real-world use of an English + abbreviation. At least for the time being, <productname>PostgreSQL</> + will continue to accept such removed abbreviations for timestamp input. + But they will not be shown in the <structname>pg_timezone_names</> + view nor used for output. + </para> + + <para> + In this update, <literal>AMT</> is no longer shown as being in use to + mean Armenia Time. Therefore, we have changed the <literal>Default</> + abbreviation set to interpret it as Amazon Time, thus UTC-4 not UTC+4. + </para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + <sect1 id="release-9-4-9"> <title>Release 9.4.9</title> - <note> - <title>Release Date</title> - <simpara>2016-08-11</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-08-11</para> + </formalpara> <para> This release contains a variety of fixes from 9.4.8. @@ -526,10 +2101,10 @@ Branch: REL9_1_STABLE [de887cc8a] 2016-05-25 19:39:49 -0400 <sect1 id="release-9-4-8"> <title>Release 9.4.8</title> - <note> - <title>Release Date</title> - <simpara>2016-05-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-05-12</para> + </formalpara> <para> This release contains a variety of fixes from 9.4.7. @@ -789,10 +2364,10 @@ Branch: REL9_1_STABLE [de887cc8a] 2016-05-25 19:39:49 -0400 <sect1 id="release-9-4-7"> <title>Release 9.4.7</title> - <note> - <title>Release Date</title> - <simpara>2016-03-31</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-03-31</para> + </formalpara> <para> This release contains a variety of fixes from 9.4.6. @@ -929,7 +2504,7 @@ Branch: REL9_1_STABLE [de887cc8a] 2016-05-25 19:39:49 -0400 <para> This dodges a portability problem on FreeBSD-derived platforms - (including OS X). + (including macOS). </para> </listitem> @@ -1060,10 +2635,10 @@ Branch: REL9_1_STABLE [de887cc8a] 2016-05-25 19:39:49 -0400 <sect1 id="release-9-4-6"> <title>Release 9.4.6</title> - <note> - <title>Release Date</title> - <simpara>2016-02-11</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-02-11</para> + </formalpara> <para> This release contains a variety of fixes from 9.4.5. @@ -2157,10 +3732,10 @@ Branch: REL9_1_STABLE [386dcd539] 2015-12-11 19:08:40 -0500 <sect1 id="release-9-4-5"> <title>Release 9.4.5</title> - <note> - <title>Release Date</title> - <simpara>2015-10-08</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-10-08</para> + </formalpara> <para> This release contains a variety of fixes from 9.4.4. @@ -3680,10 +5255,10 @@ Branch: REL9_0_STABLE [47ac95f37] 2015-10-02 19:16:37 -0400 <sect1 id="release-9-4-4"> <title>Release 9.4.4</title> - <note> - <title>Release Date</title> - <simpara>2015-06-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-06-12</para> + </formalpara> <para> This release contains a small number of fixes from 9.4.3. @@ -3861,10 +5436,10 @@ Branch: REL9_3_STABLE [d3fdec6ae] 2015-06-03 11:58:47 -0400 <sect1 id="release-9-4-3"> <title>Release 9.4.3</title> - <note> - <title>Release Date</title> - <simpara>2015-06-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-06-04</para> + </formalpara> <para> This release contains a small number of fixes from 9.4.2. @@ -4004,10 +5579,10 @@ Branch: REL9_0_STABLE [b06649b7f] 2015-05-26 22:15:00 -0400 <sect1 id="release-9-4-2"> <title>Release 9.4.2</title> - <note> - <title>Release Date</title> - <simpara>2015-05-22</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-05-22</para> + </formalpara> <para> This release contains a variety of fixes from 9.4.1. @@ -5254,7 +6829,7 @@ Branch: REL9_3_STABLE [6347bdb31] 2015-04-05 13:01:55 -0400 <listitem> <para> - Silence some build warnings on OS X (Tom Lane) + Silence some build warnings on macOS (Tom Lane) </para> </listitem> @@ -5285,10 +6860,10 @@ Branch: REL9_0_STABLE [3c3749a3b] 2015-05-15 19:36:20 -0400 <sect1 id="release-9-4-1"> <title>Release 9.4.1</title> - <note> - <title>Release Date</title> - <simpara>2015-02-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2015-02-05</para> + </formalpara> <para> This release contains a variety of fixes from 9.4.0. @@ -5813,7 +7388,7 @@ Branch: REL9_0_STABLE [2e4946169] 2015-01-07 22:46:20 -0500 <listitem> <para> - Warn if OS X's <function>setlocale()</> starts an unwanted extra + Warn if macOS's <function>setlocale()</> starts an unwanted extra thread inside the postmaster (Noah Misch) </para> </listitem> @@ -6098,10 +7673,10 @@ Branch: REL9_4_STABLE [c2b06ab17] 2015-01-30 22:45:58 -0500 <sect1 id="release-9-4"> <title>Release 9.4</title> - <note> - <title>Release Date</title> - <simpara>2014-12-18</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2014-12-18</para> + </formalpara> <sect2> <title>Overview</title> @@ -7829,7 +9404,7 @@ Branch: REL9_4_STABLE [c2b06ab17] 2015-01-30 22:45:58 -0500 <listitem> <para> - Add ability to retrieve the current PL/PgSQL call stack + Add ability to retrieve the current PL/pgSQL call stack using <link linkend="plpgsql-call-stack"><command>GET DIAGNOSTICS</></link> (Pavel Stehule, Stephen Frost) @@ -7900,7 +9475,7 @@ Branch: REL9_4_STABLE [c2b06ab17] 2015-01-30 22:45:58 -0500 <listitem> <para> Add <xref linkend="APP-CREATEUSER"> option <option>-g</> - to specify role membership (Chistopher Browne) + to specify role membership (Christopher Browne) </para> </listitem> @@ -7918,8 +9493,9 @@ Branch: REL9_4_STABLE [c2b06ab17] 2015-01-30 22:45:58 -0500 <listitem> <para> - Make <xref linkend="APP-PGRESETXLOG"> with option <option>-n</> - output current and potentially changed values (Rajeev Rastogi) + Make <link linkend="app-pgresetwal"><application>pg_resetxlog</></> + with option <option>-n</> output current and potentially changed + values (Rajeev Rastogi) </para> </listitem> @@ -8519,8 +10095,9 @@ Branch: REL9_4_STABLE [c2b06ab17] 2015-01-30 22:45:58 -0500 <listitem> <para> - Allow <xref linkend="pgxlogdump"> to report a live log stream - with <option>--follow</> (Heikki Linnakangas) + Allow <link linkend="pgwaldump"><application>pg_xlogdump</></> + to report a live log stream with <option>--follow</> + (Heikki Linnakangas) </para> </listitem> diff --git a/doc/src/sgml/release-9.5.sgml b/doc/src/sgml/release-9.5.sgml index fa3537de10..14a9b9d3b0 100644 --- a/doc/src/sgml/release-9.5.sgml +++ b/doc/src/sgml/release-9.5.sgml @@ -1,13 +1,2136 @@ <!-- doc/src/sgml/release-9.5.sgml --> <!-- See header comment in release.sgml about typical markup --> + <sect1 id="release-9-5-7"> + <title>Release 9.5.7</title> + + <formalpara> + <title>Release date:</title> + <para>2017-05-11</para> + </formalpara> + + <para> + This release contains a variety of fixes from 9.5.6. + For information about new features in the 9.5 major release, see + <xref linkend="release-9-5">. + </para> + + <sect2> + <title>Migration to Version 9.5.7</title> + + <para> + A dump/restore is not required for those running 9.5.X. + </para> + + <para> + However, if you use foreign data servers that make use of user + passwords for authentication, see the first changelog entry below. + </para> + + <para> + Also, if you are using third-party replication tools that depend + on <quote>logical decoding</>, see the fourth changelog entry below. + </para> + + <para> + Also, if you are upgrading from a version earlier than 9.5.6, + see <xref linkend="release-9-5-6">. + </para> + </sect2> + + <sect2> + <title>Changes</title> + + <itemizedlist> + + <listitem> + <para> + Restrict visibility + of <structname>pg_user_mappings</>.<structfield>umoptions</>, to + protect passwords stored as user mapping options + (Michael Paquier, Feike Steenbergen) + </para> + + <para> + The previous coding allowed the owner of a foreign server object, + or anyone he has granted server <literal>USAGE</> permission to, + to see the options for all user mappings associated with that server. + This might well include passwords for other users. + Adjust the view definition to match the behavior of + <structname>information_schema.user_mapping_options</>, namely that + these options are visible to the user being mapped, or if the mapping + is for <literal>PUBLIC</literal> and the current user is the server + owner, or if the current user is a superuser. + (CVE-2017-7486) + </para> + + <para> + By itself, this patch will only fix the behavior in newly initdb'd + databases. If you wish to apply this change in an existing database, + you will need to do the following: + </para> + + <procedure> + <step> + <para> + Restart the postmaster after adding <literal>allow_system_table_mods + = true</> to <filename>postgresql.conf</>. (In versions + supporting <command>ALTER SYSTEM</>, you can use that to make the + configuration change, but you'll still need a restart.) + </para> + </step> + + <step> + <para> + In <emphasis>each</> database of the cluster, + run the following commands as superuser: +<programlisting> +SET search_path = pg_catalog; +CREATE OR REPLACE VIEW pg_user_mappings AS + SELECT + U.oid AS umid, + S.oid AS srvid, + S.srvname AS srvname, + U.umuser AS umuser, + CASE WHEN U.umuser = 0 THEN + 'public' + ELSE + A.rolname + END AS usename, + CASE WHEN (U.umuser <> 0 AND A.rolname = current_user) + OR (U.umuser = 0 AND pg_has_role(S.srvowner, 'USAGE')) + OR (SELECT rolsuper FROM pg_authid WHERE rolname = current_user) + THEN U.umoptions + ELSE NULL END AS umoptions + FROM pg_user_mapping U + LEFT JOIN pg_authid A ON (A.oid = U.umuser) JOIN + pg_foreign_server S ON (U.umserver = S.oid); +</programlisting> + </para> + </step> + + <step> + <para> + Do not forget to include the <literal>template0</> + and <literal>template1</> databases, or the vulnerability will still + exist in databases you create later. To fix <literal>template0</>, + you'll need to temporarily make it accept connections. + In <productname>PostgreSQL</> 9.5 and later, you can use +<programlisting> +ALTER DATABASE template0 WITH ALLOW_CONNECTIONS true; +</programlisting> + and then after fixing <literal>template0</>, undo that with +<programlisting> +ALTER DATABASE template0 WITH ALLOW_CONNECTIONS false; +</programlisting> + In prior versions, instead use +<programlisting> +UPDATE pg_database SET datallowconn = true WHERE datname = 'template0'; +UPDATE pg_database SET datallowconn = false WHERE datname = 'template0'; +</programlisting> + </para> + </step> + + <step> + <para> + Finally, remove the <literal>allow_system_table_mods</> configuration + setting, and again restart the postmaster. + </para> + </step> + </procedure> + </listitem> + + <listitem> + <para> + Prevent exposure of statistical information via leaky operators + (Peter Eisentraut) + </para> + + <para> + Some selectivity estimation functions in the planner will apply + user-defined operators to values obtained + from <structname>pg_statistic</>, such as most common values and + histogram entries. This occurs before table permissions are checked, + so a nefarious user could exploit the behavior to obtain these values + for table columns he does not have permission to read. To fix, + fall back to a default estimate if the operator's implementation + function is not certified leak-proof and the calling user does not have + permission to read the table column whose statistics are needed. + At least one of these criteria is satisfied in most cases in practice. + (CVE-2017-7484) + </para> + </listitem> + + <listitem> + <para> + Restore <application>libpq</>'s recognition of + the <envar>PGREQUIRESSL</> environment variable (Daniel Gustafsson) + </para> + + <para> + Processing of this environment variable was unintentionally dropped + in <productname>PostgreSQL</> 9.3, but its documentation remained. + This creates a security hazard, since users might be relying on the + environment variable to force SSL-encrypted connections, but that + would no longer be guaranteed. Restore handling of the variable, + but give it lower priority than <envar>PGSSLMODE</>, to avoid + breaking configurations that work correctly with post-9.3 code. + (CVE-2017-7485) + </para> + </listitem> + + <listitem> + <para> + Fix possibly-invalid initial snapshot during logical decoding + (Petr Jelinek, Andres Freund) + </para> + + <para> + The initial snapshot created for a logical decoding replication slot + was potentially incorrect. This could cause third-party tools that + use logical decoding to copy incomplete/inconsistent initial data. + This was more likely to happen if the source server was busy at the + time of slot creation, or if another logical slot already existed. + </para> + + <para> + If you are using a replication tool that depends on logical decoding, + and it should have copied a nonempty data set at the start of + replication, it is advisable to recreate the replica after + installing this update, or to verify its contents against the source + server. + </para> + </listitem> + + <listitem> + <para> + Fix possible corruption of <quote>init forks</> of unlogged indexes + (Robert Haas, Michael Paquier) + </para> + + <para> + This could result in an unlogged index being set to an invalid state + after a crash and restart. Such a problem would persist until the + index was dropped and rebuilt. + </para> + </listitem> + + <listitem> + <para> + Fix incorrect reconstruction of <structname>pg_subtrans</> entries + when a standby server replays a prepared but uncommitted two-phase + transaction (Tom Lane) + </para> + + <para> + In most cases this turned out to have no visible ill effects, but in + corner cases it could result in circular references + in <structname>pg_subtrans</>, potentially causing infinite loops + in queries that examine rows modified by the two-phase transaction. + </para> + </listitem> + + <listitem> + <para> + Avoid possible crash in <application>walsender</> due to failure + to initialize a string buffer (Stas Kelvich, Fujii Masao) + </para> + </listitem> + + <listitem> + <para> + Fix possible crash when rescanning a nearest-neighbor index-only scan + on a GiST index (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix postmaster's handling of <function>fork()</> failure for a + background worker process (Tom Lane) + </para> + + <para> + Previously, the postmaster updated portions of its state as though + the process had been launched successfully, resulting in subsequent + confusion. + </para> + </listitem> + + <listitem> +<!-- +Author: Andrew Gierth <[email protected]> +Branch: REL9_5_STABLE [7be3678a8] 2017-04-24 07:53:05 +0100 +--> + <para> + Fix crash or wrong answers when a <literal>GROUPING SETS</> column's + data type is hashable but not sortable (Pavan Deolasee) + </para> + </listitem> + + <listitem> + <para> + Avoid applying <quote>physical targetlist</> optimization to custom + scans (Dmitry Ivanov, Tom Lane) + </para> + + <para> + This optimization supposed that retrieving all columns of a tuple + is inexpensive, which is true for ordinary Postgres tuples; but it + might not be the case for a custom scan provider. + </para> + </listitem> + + <listitem> + <para> + Use the correct sub-expression when applying a <literal>FOR ALL</> + row-level-security policy (Stephen Frost) + </para> + + <para> + In some cases the <literal>WITH CHECK</> restriction would be applied + when the <literal>USING</> restriction is more appropriate. + </para> + </listitem> + + <listitem> + <para> + Ensure parsing of queries in extension scripts sees the results of + immediately-preceding DDL (Julien Rouhaud, Tom Lane) + </para> + + <para> + Due to lack of a cache flush step between commands in an extension + script file, non-utility queries might not see the effects of an + immediately preceding catalog change, such as <command>ALTER TABLE + ... RENAME</>. + </para> + </listitem> + + <listitem> + <para> + Skip tablespace privilege checks when <command>ALTER TABLE ... ALTER + COLUMN TYPE</> rebuilds an existing index (Noah Misch) + </para> + + <para> + The command failed if the calling user did not currently have + <literal>CREATE</> privilege for the tablespace containing the index. + That behavior seems unhelpful, so skip the check, allowing the + index to be rebuilt where it is. + </para> + </listitem> + + <listitem> + <para> + Fix <command>ALTER TABLE ... VALIDATE CONSTRAINT</> to not recurse + to child tables when the constraint is marked <literal>NO INHERIT</> + (Amit Langote) + </para> + + <para> + This fix prevents unwanted <quote>constraint does not exist</> failures + when no matching constraint is present in the child tables. + </para> + </listitem> + + <listitem> + <para> + Avoid dangling pointer in <command>COPY ... TO</> when row-level + security is active for the source table (Tom Lane) + </para> + + <para> + Usually this had no ill effects, but sometimes it would cause + unexpected errors or crashes. + </para> + </listitem> + + <listitem> + <para> + Avoid accessing an already-closed relcache entry in <command>CLUSTER</> + and <command>VACUUM FULL</> (Tom Lane) + </para> + + <para> + With some bad luck, this could lead to indexes on the target + relation getting rebuilt with the wrong persistence setting. + </para> + </listitem> + + <listitem> + <para> + Fix <command>VACUUM</> to account properly for pages that could not + be scanned due to conflicting page pins (Andrew Gierth) + </para> + + <para> + This tended to lead to underestimation of the number of tuples in + the table. In the worst case of a small heavily-contended + table, <command>VACUUM</> could incorrectly report that the table + contained no tuples, leading to very bad planning choices. + </para> + </listitem> + + <listitem> + <para> + Ensure that bulk-tuple-transfer loops within a hash join are + interruptible by query cancel requests (Tom Lane, Thomas Munro) + </para> + </listitem> + + <listitem> + <para> + Fix integer-overflow problems in <type>interval</> comparison (Kyotaro + Horiguchi, Tom Lane) + </para> + + <para> + The comparison operators for type <type>interval</> could yield wrong + answers for intervals larger than about 296000 years. Indexes on + columns containing such large values should be reindexed, since they + may be corrupt. + </para> + </listitem> + + <listitem> + <para> + Fix <function>cursor_to_xml()</> to produce valid output + with <replaceable>tableforest</> = false + (Thomas Munro, Peter Eisentraut) + </para> + + <para> + Previously it failed to produce a wrapping <literal><table></> + element. + </para> + </listitem> + + <listitem> + <para> + Fix roundoff problems in <function>float8_timestamptz()</> + and <function>make_interval()</> (Tom Lane) + </para> + + <para> + These functions truncated, rather than rounded, when converting a + floating-point value to integer microseconds; that could cause + unexpectedly off-by-one results. + </para> + </listitem> + + <listitem> + <para> + Fix <function>pg_get_object_address()</> to handle members of operator + families correctly (Álvaro Herrera) + </para> + </listitem> + + <listitem> + <para> + Improve performance of <structname>pg_timezone_names</> view + (Tom Lane, David Rowley) + </para> + </listitem> + + <listitem> + <para> + Reduce memory management overhead for contexts containing many large + blocks (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix sloppy handling of corner-case errors from <function>lseek()</> + and <function>close()</> (Tom Lane) + </para> + + <para> + Neither of these system calls are likely to fail in typical situations, + but if they did, <filename>fd.c</> could get quite confused. + </para> + </listitem> + + <listitem> + <para> + Fix incorrect check for whether postmaster is running as a Windows + service (Michael Paquier) + </para> + + <para> + This could result in attempting to write to the event log when that + isn't accessible, so that no logging happens at all. + </para> + </listitem> + + <listitem> + <para> + Fix <application>ecpg</> to support <command>COMMIT PREPARED</> + and <command>ROLLBACK PREPARED</> (Masahiko Sawada) + </para> + </listitem> + + <listitem> + <para> + Fix a double-free error when processing dollar-quoted string literals + in <application>ecpg</> (Michael Meskes) + </para> + </listitem> + + <listitem> + <para> + In <application>pg_dump</>, fix incorrect schema and owner marking for + comments and security labels of some types of database objects + (Giuseppe Broccolo, Tom Lane) + </para> + + <para> + In simple cases this caused no ill effects; but for example, a + schema-selective restore might omit comments it should include, because + they were not marked as belonging to the schema of their associated + object. + </para> + </listitem> + + <listitem> + <para> + Avoid emitting an invalid list file in <literal>pg_restore -l</> + when SQL object names contain newlines (Tom Lane) + </para> + + <para> + Replace newlines by spaces, which is sufficient to make the output + valid for <literal>pg_restore -L</>'s purposes. + </para> + </listitem> + + <listitem> + <para> + Fix <application>pg_upgrade</> to transfer comments and security labels + attached to <quote>large objects</> (blobs) (Stephen Frost) + </para> + + <para> + Previously, blobs were correctly transferred to the new database, but + any comments or security labels attached to them were lost. + </para> + </listitem> + + <listitem> + <para> + Improve error handling + in <filename>contrib/adminpack</>'s <function>pg_file_write()</> + function (Noah Misch) + </para> + + <para> + Notably, it failed to detect errors reported + by <function>fclose()</>. + </para> + </listitem> + + <listitem> + <para> + In <filename>contrib/dblink</>, avoid leaking the previous unnamed + connection when establishing a new unnamed connection (Joe Conway) + </para> + </listitem> + + <listitem> + <para> + Fix <filename>contrib/pg_trgm</>'s extraction of trigrams from regular + expressions (Tom Lane) + </para> + + <para> + In some cases it would produce a broken data structure that could never + match anything, leading to GIN or GiST indexscans that use a trigram + index not finding any matches to the regular expression. + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: REL9_5_STABLE [cdf5a004b] 2017-05-06 22:21:38 -0400 +Branch: REL9_4_STABLE [f14bf0a8f] 2017-05-06 22:19:56 -0400 +Branch: REL9_3_STABLE [3aa16b117] 2017-05-06 22:17:35 -0400 +--> + <para> + In <filename>contrib/postgres_fdw</>, + transmit query cancellation requests to the remote server + (Michael Paquier, Etsuro Fujita) + </para> + + <para> + Previously, a local query cancellation request did not cause an + already-sent remote query to terminate early. This is a back-patch + of work originally done for 9.6. + </para> + </listitem> + + <listitem> + <para> + Support Tcl 8.6 in MSVC builds (Álvaro Herrera) + </para> + </listitem> + + <listitem> + <para> + Sync our copy of the timezone library with IANA release tzcode2017b + (Tom Lane) + </para> + + <para> + This fixes a bug affecting some DST transitions in January 2038. + </para> + </listitem> + + <listitem> + <para> + Update time zone data files to <application>tzdata</> release 2017b + for DST law changes in Chile, Haiti, and Mongolia, plus historical + corrections for Ecuador, Kazakhstan, Liberia, and Spain. + Switch to numeric abbreviations for numerous time zones in South + America, the Pacific and Indian oceans, and some Asian and Middle + Eastern countries. + </para> + + <para> + The IANA time zone database previously provided textual abbreviations + for all time zones, sometimes making up abbreviations that have little + or no currency among the local population. They are in process of + reversing that policy in favor of using numeric UTC offsets in zones + where there is no evidence of real-world use of an English + abbreviation. At least for the time being, <productname>PostgreSQL</> + will continue to accept such removed abbreviations for timestamp input. + But they will not be shown in the <structname>pg_timezone_names</> + view nor used for output. + </para> + </listitem> + + <listitem> + <para> + Use correct daylight-savings rules for POSIX-style time zone names + in MSVC builds (David Rowley) + </para> + + <para> + The Microsoft MSVC build scripts neglected to install + the <filename>posixrules</> file in the timezone directory tree. + This resulted in the timezone code falling back to its built-in + rule about what DST behavior to assume for a POSIX-style time zone + name. For historical reasons that still corresponds to the DST rules + the USA was using before 2007 (i.e., change on first Sunday in April + and last Sunday in October). With this fix, a POSIX-style zone name + will use the current and historical DST transition dates of + the <literal>US/Eastern</> zone. If you don't want that, remove + the <filename>posixrules</> file, or replace it with a copy of some + other zone file (see <xref linkend="datatype-timezones">). Note that + due to caching, you may need to restart the server to get such changes + to take effect. + </para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + + <sect1 id="release-9-5-6"> + <title>Release 9.5.6</title> + + <formalpara> + <title>Release date:</title> + <para>2017-02-09</para> + </formalpara> + + <para> + This release contains a variety of fixes from 9.5.5. + For information about new features in the 9.5 major release, see + <xref linkend="release-9-5">. + </para> + + <sect2> + <title>Migration to Version 9.5.6</title> + + <para> + A dump/restore is not required for those running 9.5.X. + </para> + + <para> + However, if your installation has been affected by the bug described in + the first changelog entry below, then after updating you may need + to take action to repair corrupted indexes. + </para> + + <para> + Also, if you are upgrading from a version earlier than 9.5.5, + see <xref linkend="release-9-5-5">. + </para> + </sect2> + + <sect2> + <title>Changes</title> + + <itemizedlist> + + <listitem> + <para> + Fix a race condition that could cause indexes built + with <command>CREATE INDEX CONCURRENTLY</> to be corrupt + (Pavan Deolasee, Tom Lane) + </para> + + <para> + If <command>CREATE INDEX CONCURRENTLY</> was used to build an index + that depends on a column not previously indexed, then rows + updated by transactions that ran concurrently with + the <command>CREATE INDEX</> command could have received incorrect + index entries. If you suspect this may have happened, the most + reliable solution is to rebuild affected indexes after installing + this update. + </para> + </listitem> + + <listitem> + <para> + Ensure that the special snapshot used for catalog scans is not + invalidated by premature data pruning (Tom Lane) + </para> + + <para> + Backends failed to account for this snapshot when advertising their + oldest xmin, potentially allowing concurrent vacuuming operations to + remove data that was still needed. This led to transient failures + along the lines of <quote>cache lookup failed for relation 1255</>. + </para> + </listitem> + + <listitem> + <para> + Fix incorrect WAL logging for BRIN indexes (Kuntal Ghosh) + </para> + + <para> + The WAL record emitted for a BRIN <quote>revmap</> page when moving an + index tuple to a different page was incorrect. Replay would make the + related portion of the index useless, forcing it to be recomputed. + </para> + </listitem> + + <listitem> + <para> + Unconditionally WAL-log creation of the <quote>init fork</> for an + unlogged table (Michael Paquier) + </para> + + <para> + Previously, this was skipped when <xref linkend="guc-wal-level"> + = <literal>minimal</>, but actually it's necessary even in that case + to ensure that the unlogged table is properly reset to empty after a + crash. + </para> + </listitem> + + <listitem> +<!-- +Author: Alvaro Herrera <[email protected]> +Branch: REL9_5_STABLE [c0db1ec26] 2016-11-17 13:31:30 -0300 +Branch: REL9_4_STABLE [30e3cb307] 2016-11-17 13:31:30 -0300 +--> + <para> + Reduce interlocking on standby servers during the replay of btree + index vacuuming operations (Simon Riggs) + </para> + + <para> + This change avoids substantial replication delays that sometimes + occurred while replaying such operations. + </para> + </listitem> + + <listitem> + <para> + If the stats collector dies during hot standby, restart it (Takayuki + Tsunakawa) + </para> + </listitem> + + <listitem> + <para> + Ensure that hot standby feedback works correctly when it's enabled at + standby server start (Ants Aasma, Craig Ringer) + </para> + </listitem> + + <listitem> + <para> + Check for interrupts while hot standby is waiting for a conflicting + query (Simon Riggs) + </para> + </listitem> + + <listitem> + <para> + Avoid constantly respawning the autovacuum launcher in a corner case + (Amit Khandekar) + </para> + + <para> + This fix avoids problems when autovacuum is nominally off and there + are some tables that require freezing, but all such tables are + already being processed by autovacuum workers. + </para> + </listitem> + + <listitem> + <para> + Fix check for when an extension member object can be dropped (Tom Lane) + </para> + + <para> + Extension upgrade scripts should be able to drop member objects, + but this was disallowed for serial-column sequences, and possibly + other cases. + </para> + </listitem> + + <listitem> + <para> + Make sure <command>ALTER TABLE</> preserves index tablespace + assignments when rebuilding indexes (Tom Lane, Michael Paquier) + </para> + + <para> + Previously, non-default settings + of <xref linkend="guc-default-tablespace"> could result in broken + indexes. + </para> + </listitem> + + <listitem> + <para> + Fix incorrect updating of trigger function properties when changing a + foreign-key constraint's deferrability properties with <command>ALTER + TABLE ... ALTER CONSTRAINT</> (Tom Lane) + </para> + + <para> + This led to odd failures during subsequent exercise of the foreign + key, as the triggers were fired at the wrong times. + </para> + </listitem> + + <listitem> + <para> + Prevent dropping a foreign-key constraint if there are pending + trigger events for the referenced relation (Tom Lane) + </para> + + <para> + This avoids <quote>could not find trigger <replaceable>NNN</></quote> + or <quote>relation <replaceable>NNN</> has no triggers</quote> errors. + </para> + </listitem> + + <listitem> + <para> + Fix <command>ALTER TABLE ... SET DATA TYPE ... USING</> when child + table has different column ordering than the parent + (Álvaro Herrera) + </para> + + <para> + Failure to adjust the column numbering in the <literal>USING</> + expression led to errors, + typically <quote>attribute <replaceable>N</> has wrong type</quote>. + </para> + </listitem> + + <listitem> + <para> + Fix processing of OID column when a table with OIDs is associated to + a parent with OIDs via <command>ALTER TABLE ... INHERIT</> (Amit + Langote) + </para> + + <para> + The OID column should be treated the same as regular user columns in + this case, but it wasn't, leading to odd behavior in later + inheritance changes. + </para> + </listitem> + + <listitem> + <para> + Fix <command>CREATE OR REPLACE VIEW</> to update the view query + before attempting to apply the new view options (Dean Rasheed) + </para> + + <para> + Previously the command would fail if the new options were + inconsistent with the old view definition. + </para> + </listitem> + + <listitem> + <para> + Report correct object identity during <command>ALTER TEXT SEARCH + CONFIGURATION</> (Artur Zakirov) + </para> + + <para> + The wrong catalog OID was reported to extensions such as logical + decoding. + </para> + </listitem> + + <listitem> + <para> + Fix commit timestamp mechanism to not fail when queried about + the special XIDs <literal>FrozenTransactionId</> + and <literal>BootstrapTransactionId</> (Craig Ringer) + </para> + </listitem> + + <listitem> +<!-- +Author: Kevin Grittner <[email protected]> +Branch: REL9_5_STABLE [bed2a0b06] 2016-12-13 19:14:42 -0600 +Branch: REL9_4_STABLE [4b9d466c1] 2016-12-13 19:05:12 -0600 +Branch: REL9_3_STABLE [5d80171ad] 2016-12-13 19:05:35 -0600 +Branch: REL9_2_STABLE [60314e28e] 2016-12-13 19:08:09 -0600 +--> + <para> + Check for serializability conflicts before reporting + constraint-violation failures (Thomas Munro) + </para> + + <para> + When using serializable transaction isolation, it is desirable + that any error due to concurrent transactions should manifest + as a serialization failure, thereby cueing the application that + a retry might succeed. Unfortunately, this does not reliably + happen for duplicate-key failures caused by concurrent insertions. + This change ensures that such an error will be reported as a + serialization error if the application explicitly checked for + the presence of a conflicting key (and did not find it) earlier + in the transaction. + </para> + </listitem> + + <listitem> + <para> + Fix incorrect use of view reloptions as regular table reloptions (Tom + Lane) + </para> + + <para> + The symptom was spurious <quote>ON CONFLICT is not supported on table + ... used as a catalog table</> errors when the target + of <command>INSERT ... ON CONFLICT</> is a view with cascade option. + </para> + </listitem> + + <listitem> + <para> + Fix incorrect <quote>target lists can have at most <replaceable>N</> + entries</quote> complaint when using <literal>ON CONFLICT</> with + wide tables (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Prevent multicolumn expansion of <replaceable>foo</><literal>.*</> in + an <command>UPDATE</> source expression (Tom Lane) + </para> + + <para> + This led to <quote>UPDATE target count mismatch --- internal + error</>. Now the syntax is understood as a whole-row variable, + as it would be in other contexts. + </para> + </listitem> + + <listitem> + <para> + Ensure that column typmods are determined accurately for + multi-row <literal>VALUES</> constructs (Tom Lane) + </para> + + <para> + This fixes problems occurring when the first value in a column has a + determinable typmod (e.g., length for a <type>varchar</> value) but + later values don't share the same limit. + </para> + </listitem> + + <listitem> + <para> + Throw error for an unfinished Unicode surrogate pair at the end of a + Unicode string (Tom Lane) + </para> + + <para> + Normally, a Unicode surrogate leading character must be followed by a + Unicode surrogate trailing character, but the check for this was + missed if the leading character was the last character in a Unicode + string literal (<literal>U&'...'</>) or Unicode identifier + (<literal>U&"..."</>). + </para> + </listitem> + + <listitem> + <para> + Ensure that a purely negative text search query, such + as <literal>!foo</>, matches empty <type>tsvector</>s (Tom Dunstan) + </para> + + <para> + Such matches were found by GIN index searches, but not by sequential + scans or GiST index searches. + </para> + </listitem> + + <listitem> + <para> + Prevent crash when <function>ts_rewrite()</> replaces a non-top-level + subtree with an empty query (Artur Zakirov) + </para> + </listitem> + + <listitem> + <para> + Fix performance problems in <function>ts_rewrite()</> (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix <function>ts_rewrite()</>'s handling of nested NOT operators + (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Improve speed of user-defined aggregates that + use <function>array_append()</> as transition function (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix <function>array_fill()</> to handle empty arrays properly (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix possible crash in <function>array_position()</> + or <function>array_positions()</> when processing arrays of records + (Junseok Yang) + </para> + </listitem> + + <listitem> + <para> + Fix one-byte buffer overrun in <function>quote_literal_cstr()</> + (Heikki Linnakangas) + </para> + + <para> + The overrun occurred only if the input consisted entirely of single + quotes and/or backslashes. + </para> + </listitem> + + <listitem> + <para> + Prevent multiple calls of <function>pg_start_backup()</> + and <function>pg_stop_backup()</> from running concurrently (Michael + Paquier) + </para> + + <para> + This avoids an assertion failure, and possibly worse things, if + someone tries to run these functions in parallel. + </para> + </listitem> + + <listitem> + <para> + Disable transform that attempted to remove no-op <literal>AT TIME + ZONE</> conversions (Tom Lane) + </para> + + <para> + This resulted in wrong answers when the simplified expression was + used in an index condition. + </para> + </listitem> + + <listitem> + <para> + Avoid discarding <type>interval</>-to-<type>interval</> casts + that aren't really no-ops (Tom Lane) + </para> + + <para> + In some cases, a cast that should result in zeroing out + low-order <type>interval</> fields was mistakenly deemed to be a + no-op and discarded. An example is that casting from <type>INTERVAL + MONTH</> to <type>INTERVAL YEAR</> failed to clear the months field. + </para> + </listitem> + + <listitem> + <para> + Fix bugs in transmitting GUC parameter values to parallel workers + (Michael Paquier, Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Ensure that cached plans are invalidated by changes in foreign-table + options (Amit Langote, Etsuro Fujita, Ashutosh Bapat) + </para> + </listitem> + + <listitem> + <para> + Fix <application>pg_dump</> to dump user-defined casts and transforms + that use built-in functions (Stephen Frost) + </para> + </listitem> + + <listitem> + <para> + Fix <application>pg_restore</> with <option>--create --if-exists</> + to behave more sanely if an archive contains + unrecognized <command>DROP</> commands (Tom Lane) + </para> + + <para> + This doesn't fix any live bug, but it may improve the behavior in + future if <application>pg_restore</> is used with an archive + generated by a later <application>pg_dump</> version. + </para> + </listitem> + + <listitem> + <para> + Fix <application>pg_basebackup</>'s rate limiting in the presence of + slow I/O (Antonin Houska) + </para> + + <para> + If disk I/O was transiently much slower than the specified rate + limit, the calculation overflowed, effectively disabling the rate + limit for the rest of the run. + </para> + </listitem> + + <listitem> + <para> + Fix <application>pg_basebackup</>'s handling of + symlinked <filename>pg_stat_tmp</> and <filename>pg_replslot</> + subdirectories (Magnus Hagander, Michael Paquier) + </para> + </listitem> + + <listitem> + <para> + Fix possible <application>pg_basebackup</> failure on standby + server when including WAL files (Amit Kapila, Robert Haas) + </para> + </listitem> + + <listitem> + <para> + Fix possible mishandling of expanded arrays in domain check + constraints and <literal>CASE</> execution (Tom Lane) + </para> + + <para> + It was possible for a PL/pgSQL function invoked in these contexts to + modify or even delete an array value that needs to be preserved for + additional operations. + </para> + </listitem> + + <listitem> + <para> + Fix nested uses of PL/pgSQL functions in contexts such as domain + check constraints evaluated during assignment to a PL/pgSQL variable + (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Ensure that the Python exception objects we create for PL/Python are + properly reference-counted (Rafa de la Torre, Tom Lane) + </para> + + <para> + This avoids failures if the objects are used after a Python garbage + collection cycle has occurred. + </para> + </listitem> + + <listitem> + <para> + Fix PL/Tcl to support triggers on tables that have <literal>.tupno</> + as a column name (Tom Lane) + </para> + + <para> + This matches the (previously undocumented) behavior of + PL/Tcl's <command>spi_exec</> and <command>spi_execp</> commands, + namely that a magic <literal>.tupno</> column is inserted only if + there isn't a real column named that. + </para> + </listitem> + + <listitem> + <para> + Allow DOS-style line endings in <filename>~/.pgpass</> files, + even on Unix (Vik Fearing) + </para> + + <para> + This change simplifies use of the same password file across Unix and + Windows machines. + </para> + </listitem> + + <listitem> + <para> + Fix one-byte buffer overrun if <application>ecpg</> is given a file + name that ends with a dot (Takayuki Tsunakawa) + </para> + </listitem> + + <listitem> + <para> + Fix <application>psql</>'s tab completion for <command>ALTER DEFAULT + PRIVILEGES</> (Gilles Darold, Stephen Frost) + </para> + </listitem> + + <listitem> + <para> + In <application>psql</>, treat an empty or all-blank setting of + the <envar>PAGER</> environment variable as meaning <quote>no + pager</> (Tom Lane) + </para> + + <para> + Previously, such a setting caused output intended for the pager to + vanish entirely. + </para> + </listitem> + + <listitem> + <para> + Improve <filename>contrib/dblink</>'s reporting of + low-level <application>libpq</> errors, such as out-of-memory + (Joe Conway) + </para> + </listitem> + + <listitem> + <para> + Teach <filename>contrib/dblink</> to ignore irrelevant server options + when it uses a <filename>contrib/postgres_fdw</> foreign server as + the source of connection options (Corey Huinker) + </para> + + <para> + Previously, if the foreign server object had options that were not + also <application>libpq</> connection options, an error occurred. + </para> + </listitem> + + <listitem> + <para> + Fix portability problems in <filename>contrib/pageinspect</>'s + functions for GIN indexes (Peter Eisentraut, Tom Lane) + </para> + </listitem> + + <listitem> + <para> + On Windows, ensure that environment variable changes are propagated + to DLLs built with debug options (Christian Ullrich) + </para> + </listitem> + + <listitem> + <para> + Sync our copy of the timezone library with IANA release tzcode2016j + (Tom Lane) + </para> + + <para> + This fixes various issues, most notably that timezone data + installation failed if the target directory didn't support hard + links. + </para> + </listitem> + + <listitem> + <para> + Update time zone data files to <application>tzdata</> release 2016j + for DST law changes in northern Cyprus (adding a new zone + Asia/Famagusta), Russia (adding a new zone Europe/Saratov), Tonga, + and Antarctica/Casey. + Historical corrections for Italy, Kazakhstan, Malta, and Palestine. + Switch to preferring numeric zone abbreviations for Tonga. + </para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + + <sect1 id="release-9-5-5"> + <title>Release 9.5.5</title> + + <formalpara> + <title>Release date:</title> + <para>2016-10-27</para> + </formalpara> + + <para> + This release contains a variety of fixes from 9.5.4. + For information about new features in the 9.5 major release, see + <xref linkend="release-9-5">. + </para> + + <sect2> + <title>Migration to Version 9.5.5</title> + + <para> + A dump/restore is not required for those running 9.5.X. + </para> + + <para> + However, if your installation has been affected by the bug described in + the first changelog entry below, then after updating you may need + to take action to repair corrupted free space maps. + </para> + + <para> + Also, if you are upgrading from a version earlier than 9.5.2, + see <xref linkend="release-9-5-2">. + </para> + </sect2> + + <sect2> + <title>Changes</title> + + <itemizedlist> + + <listitem> + <para> + Fix WAL-logging of truncation of relation free space maps and + visibility maps (Pavan Deolasee, Heikki Linnakangas) + </para> + + <para> + It was possible for these files to not be correctly restored during + crash recovery, or to be written incorrectly on a standby server. + Bogus entries in a free space map could lead to attempts to access + pages that have been truncated away from the relation itself, typically + producing errors like <quote>could not read block <replaceable>XXX</>: + read only 0 of 8192 bytes</quote>. Checksum failures in the + visibility map are also possible, if checksumming is enabled. + </para> + + <para> + Procedures for determining whether there is a problem and repairing it + if so are discussed at + <ulink url="https://wiki.postgresql.org/wiki/Free_Space_Map_Problems"></>. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [60893786d] 2016-09-03 13:28:53 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [36646d3af] 2016-09-03 13:28:53 -0400 +Branch: REL9_5_STABLE [08a72872f] 2016-09-03 13:28:53 -0400 +Branch: REL9_4_STABLE [a69443564] 2016-09-03 13:28:53 -0400 +--> + <para> + Fix incorrect creation of GIN index WAL records on big-endian machines + (Tom Lane) + </para> + + <para> + The typical symptom was <quote>unexpected GIN leaf action</> errors + during WAL replay. + </para> + </listitem> + + <listitem> +<!-- +Author: Alvaro Herrera <[email protected]> +Branch: master [5c609a742] 2016-09-09 15:54:29 -0300 +Branch: REL9_6_STABLE Release: REL9_6_0 [c3656c9ff] 2016-09-09 15:54:29 -0300 +Branch: REL9_5_STABLE [f33765885] 2016-09-09 15:54:29 -0300 +Branch: REL9_4_STABLE [8778da2af] 2016-09-09 15:54:29 -0300 +Branch: REL9_3_STABLE [dfe7121df] 2016-09-09 15:54:29 -0300 +--> + <para> + Fix <command>SELECT FOR UPDATE/SHARE</> to correctly lock tuples that + have been updated by a subsequently-aborted transaction + (Álvaro Herrera) + </para> + + <para> + In 9.5 and later, the <command>SELECT</> would sometimes fail to + return such tuples at all. A failure has not been proven to occur in + earlier releases, but might be possible with concurrent updates. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [96dd77d34] 2016-09-22 11:35:03 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [a88fe25f5] 2016-09-22 11:34:44 -0400 +Branch: REL9_5_STABLE [c35917835] 2016-09-22 11:34:44 -0400 +Branch: REL9_4_STABLE [d3dd00e67] 2016-09-22 11:34:44 -0400 +Branch: REL9_3_STABLE [73df86a37] 2016-09-22 11:34:44 -0400 +Branch: REL9_2_STABLE [8552f9b90] 2016-09-22 11:34:44 -0400 +Branch: REL9_1_STABLE [0183df5dc] 2016-09-22 11:34:45 -0400 +--> + <para> + Fix EvalPlanQual rechecks involving CTE scans (Tom Lane) + </para> + + <para> + The recheck would always see the CTE as returning no rows, typically + leading to failure to update rows that were recently updated. + </para> + </listitem> + + <listitem> +<!-- +Author: Andres Freund <[email protected]> +Branch: master [07ef03512] 2016-08-17 17:03:36 -0700 +Branch: REL9_6_STABLE Release: REL9_6_0 [e79aaebcc] 2016-08-17 17:03:36 -0700 +Branch: REL9_5_STABLE [94bc30725] 2016-08-17 17:03:36 -0700 +--> + <para> + Fix deletion of speculatively inserted TOAST tuples when backing out + of <command>INSERT ... ON CONFLICT</> (Oskari Saarenmaa) + </para> + + <para> + In the race condition where two transactions try to insert conflicting + tuples at about the same time, the loser would fail with + an <quote>attempted to delete invisible tuple</> error if its + insertion included any TOAST'ed fields. + </para> + </listitem> + + <listitem> + <para> + Don't throw serialization errors for self-conflicting insertions + in <command>INSERT ... ON CONFLICT</> (Thomas Munro, Peter Geoghegan) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [2c00fad28] 2016-08-24 14:38:12 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [616be05df] 2016-08-24 14:38:13 -0400 +Branch: REL9_5_STABLE [25fe5f758] 2016-08-24 14:37:50 -0400 +Branch: REL9_4_STABLE [08a823e53] 2016-08-24 14:37:51 -0400 +Branch: REL9_3_STABLE [aaad96e40] 2016-08-24 14:37:51 -0400 +Branch: REL9_2_STABLE [237663897] 2016-08-24 14:37:51 -0400 +Branch: REL9_1_STABLE [3570ea424] 2016-08-24 14:37:51 -0400 +--> + <para> + Fix improper repetition of previous results from hashed aggregation in + a subquery (Andrew Gierth) + </para> + + <para> + The test to see if we can reuse a previously-computed hash table of + the aggregate state values neglected the possibility of an outer query + reference appearing in an aggregate argument expression. A change in + the value of such a reference should lead to recalculating the hash + table, but did not. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [ae4760d66] 2016-08-24 22:20:25 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [006fb80a5] 2016-08-24 22:20:26 -0400 +Branch: REL9_5_STABLE [46bd14a10] 2016-08-24 22:20:01 -0400 +Branch: REL9_4_STABLE [566afa15c] 2016-08-24 22:20:01 -0400 +--> + <para> + Fix query-lifespan memory leak in a bulk <command>UPDATE</> on a table + with a <literal>PRIMARY KEY</> or <literal>REPLICA IDENTITY</> index + (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Fix <command>COPY</> with a column name list from a table that has + row-level security enabled (Adam Brightwell) + </para> + </listitem> + + <listitem> + <para> + Fix <command>EXPLAIN</> to emit valid XML when + <xref linkend="guc-track-io-timing"> is on (Markus Winand) + </para> + + <para> + Previously the XML output-format option produced syntactically invalid + tags such as <literal><I/O-Read-Time></>. That is now + rendered as <literal><I-O-Read-Time></>. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master Release: REL9_6_BR [4b234fd8b] 2016-08-12 12:13:04 -0400 +Branch: REL9_5_STABLE [ed2d7b8c8] 2016-08-12 12:13:04 -0400 +Branch: REL9_4_STABLE [85974b468] 2016-08-12 12:13:04 -0400 +Branch: REL9_3_STABLE [16cc6d23b] 2016-08-12 12:13:04 -0400 +Branch: REL9_2_STABLE [ceb005319] 2016-08-12 12:13:04 -0400 +--> + <para> + Suppress printing of zeroes for unmeasured times + in <command>EXPLAIN</> (Maksim Milyutin) + </para> + + <para> + Certain option combinations resulted in printing zero values for times + that actually aren't ever measured in that combination. Our general + policy in <command>EXPLAIN</> is not to print such fields at all, so + do that consistently in all cases. + </para> + </listitem> + + <listitem> + <para> + Fix statistics update for <command>TRUNCATE</> in a prepared + transaction (Stas Kelvich) + </para> + </listitem> + + <listitem> +<!-- +Author: Simon Riggs <[email protected]> +Branch: master [dcb12ce8d] 2016-09-06 15:35:47 +0100 +Branch: REL9_6_STABLE Release: REL9_6_0 [1fa42debe] 2016-09-09 11:43:08 +0100 +Branch: REL9_5_STABLE [f3b3e871e] 2016-09-09 11:43:46 +0100 +Branch: REL9_4_STABLE [81b0f8204] 2016-09-09 11:44:54 +0100 +Branch: REL9_3_STABLE [e1dddf3e8] 2016-09-09 11:45:16 +0100 +Branch: REL9_2_STABLE [eaf6fe7fa] 2016-09-09 11:45:40 +0100 +Branch: REL9_1_STABLE [3ed7f54bc] 2016-09-09 11:46:03 +0100 +--> + <para> + Fix timeout length when <command>VACUUM</> is waiting for exclusive + table lock so that it can truncate the table (Simon Riggs) + </para> + + <para> + The timeout was meant to be 50 milliseconds, but it was actually only + 50 microseconds, causing <command>VACUUM</> to give up on truncation + much more easily than intended. Set it to the intended value. + </para> + </listitem> + + <listitem> + <para> + Fix bugs in merging inherited <literal>CHECK</> constraints while + creating or altering a table (Tom Lane, Amit Langote) + </para> + + <para> + Allow identical <literal>CHECK</> constraints to be added to a parent + and child table in either order. Prevent merging of a valid + constraint from the parent table with a <literal>NOT VALID</> + constraint on the child. Likewise, prevent merging of a <literal>NO + INHERIT</> child constraint with an inherited constraint. + </para> + </listitem> + + <listitem> + <para> + Show a sensible value + in <structname>pg_settings</>.<structfield>unit</> + for <varname>min_wal_size</> and <varname>max_wal_size</> (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master Release: REL9_6_BR [9389fbd03] 2016-08-14 15:06:01 -0400 +Branch: REL9_5_STABLE [635651214] 2016-08-14 15:06:01 -0400 +Branch: REL9_4_STABLE [4ac3d7794] 2016-08-14 15:06:01 -0400 +Branch: REL9_3_STABLE [e8e20aadd] 2016-08-14 15:06:02 -0400 +Branch: REL9_2_STABLE [9d5bf77b5] 2016-08-14 15:06:02 -0400 +Branch: REL9_1_STABLE [7e01c8ef3] 2016-08-14 15:06:02 -0400 +--> + <para> + Remove artificial restrictions on the values accepted + by <function>numeric_in()</> and <function>numeric_recv()</> + (Tom Lane) + </para> + + <para> + We allow numeric values up to the limit of the storage format (more + than <literal>1e100000</>), so it seems fairly pointless + that <function>numeric_in()</> rejected scientific-notation exponents + above 1000. Likewise, it was silly for <function>numeric_recv()</> to + reject more than 1000 digits in an input value. + </para> + </listitem> + + <listitem> + <para> + Avoid very-low-probability data corruption due to testing tuple + visibility without holding buffer lock (Thomas Munro, Peter Geoghegan, + Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Preserve commit timestamps across server restart + (Julien Rouhaud, Craig Ringer) + </para> + + <para> + With <xref linkend="guc-track-commit-timestamp"> turned on, old + commit timestamps became inaccessible after a clean server restart. + </para> + </listitem> + + <listitem> + <para> + Fix logical WAL decoding to work properly when a subtransaction's WAL + output is large enough to spill to disk (Andres Freund) + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [008c4135c] 2016-08-22 15:22:11 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [48b9ca0b6] 2016-08-22 15:30:31 -0400 +Branch: REL9_5_STABLE [da9659f87] 2016-08-22 15:30:37 -0400 +--> + <para> + Fix possible sorting error when aborting use of abbreviated keys + (Peter Geoghegan) + </para> + + <para> + In the worst case, this could result in a corrupt btree index, which + would need to be rebuilt using <command>REINDEX</>. However, the + situation is believed to be rare. + </para> + </listitem> + + <listitem> +<!-- +Author: Andres Freund <[email protected]> +Branch: master [769fd9d8e] 2016-09-08 16:51:09 -0700 +Branch: REL9_6_STABLE Release: REL9_6_0 [f6802936a] 2016-09-08 16:52:13 -0700 +Branch: REL9_5_STABLE [26ce63ce7] 2016-09-08 16:52:13 -0700 +Branch: REL9_4_STABLE [075cfbe4a] 2016-09-08 16:52:13 -0700 +Branch: REL9_3_STABLE [d2a5b2b28] 2016-09-08 16:52:13 -0700 +Branch: REL9_2_STABLE [f5462dedb] 2016-09-08 16:52:13 -0700 +Branch: REL9_1_STABLE [08fdfe7a8] 2016-09-08 16:52:13 -0700 +--> + <para> + Fix file descriptor leakage when truncating a temporary relation of + more than 1GB (Andres Freund) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [0e0f43d6f] 2016-08-31 08:52:13 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [3fc489cb3] 2016-08-31 08:52:13 -0400 +Branch: REL9_5_STABLE [c40bb1155] 2016-08-31 08:52:13 -0400 +Branch: REL9_4_STABLE [f4e40537e] 2016-08-31 08:52:13 -0400 +Branch: REL9_3_STABLE [baf111d31] 2016-08-31 08:52:13 -0400 +Branch: REL9_2_STABLE [823df401d] 2016-08-31 08:52:13 -0400 +Branch: REL9_1_STABLE [e3439a455] 2016-08-31 08:52:13 -0400 +--> + <para> + Disallow starting a standalone backend with <literal>standby_mode</> + turned on (Michael Paquier) + </para> + + <para> + This can't do anything useful, since there will be no WAL receiver + process to fetch more WAL data; and it could result in misbehavior + in code that wasn't designed with this situation in mind. + </para> + </listitem> + + <listitem> +<!-- +Author: Andres Freund <[email protected]> +Branch: master [2d7e59100] 2016-08-17 13:15:03 -0700 +Branch: REL9_6_STABLE Release: REL9_6_0 [8cb23dba8] 2016-08-17 13:15:03 -0700 +Branch: REL9_5_STABLE [de396a1cb] 2016-08-17 13:15:03 -0700 +Branch: REL9_4_STABLE [690a2fb90] 2016-08-17 13:15:04 -0700 +--> + <para> + Properly initialize replication slot state when recycling a + previously-used slot (Michael Paquier) + </para> + + <para> + This failure to reset all of the fields of the slot could + prevent <command>VACUUM</> from removing dead tuples. + </para> + </listitem> + + <listitem> + <para> + Round shared-memory allocation request to a multiple of the actual + huge page size when attempting to use huge pages on Linux (Tom Lane) + </para> + + <para> + This avoids possible failures during <function>munmap()</> on systems + with atypical default huge page sizes. Except in crash-recovery + cases, there were no ill effects other than a log message. + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [470d886c3] 2016-09-20 12:26:29 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [92668cd4d] 2016-09-20 12:28:02 -0400 +Branch: REL9_5_STABLE [b1aed95f5] 2016-09-20 12:30:38 -0400 +Branch: REL9_4_STABLE [626312d1b] 2016-09-20 12:30:42 -0400 +Author: Tom Lane <[email protected]> +Branch: master [49a91b88e] 2016-09-23 09:54:11 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [b251379fb] 2016-09-23 09:54:11 -0400 +Branch: REL9_5_STABLE [93528f7b4] 2016-09-23 09:54:11 -0400 +Branch: REL9_4_STABLE [32cdf680f] 2016-09-23 09:54:11 -0400 +--> + <para> + Use a more random value for the dynamic shared memory control + segment's ID (Robert Haas, Tom Lane) + </para> + + <para> + Previously, the same value would be chosen every time, because it was + derived from <function>random()</> but <function>srandom()</> had not + yet been called. While relatively harmless, this was not the intended + behavior. + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [419113dfd] 2016-09-20 12:04:41 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [6bcd26c43] 2016-09-20 12:12:27 -0400 +Branch: REL9_5_STABLE [c124e3649] 2016-09-20 12:12:31 -0400 +Branch: REL9_4_STABLE [c23b2523d] 2016-09-20 12:12:36 -0400 +--> + <para> + On Windows, retry creation of the dynamic shared memory control + segment after an access-denied error (Kyotaro Horiguchi, Amit Kapila) + </para> + + <para> + Windows sometimes returns <literal>ERROR_ACCESS_DENIED</> rather + than <literal>ERROR_ALREADY_EXISTS</> when there is an existing + segment. This led to postmaster startup failure due to believing that + the former was an unrecoverable error. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [5697522d8] 2016-08-18 14:49:08 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [c81c71d88] 2016-08-18 14:48:51 -0400 +Branch: REL9_5_STABLE [a8fc19505] 2016-08-18 14:48:51 -0400 +--> + <para> + Fix <application>PL/pgSQL</> to not misbehave with parameters and + local variables of type <type>int2vector</> or <type>oidvector</> + (Tom Lane) + </para> + </listitem> + + <listitem> + <para> + Don't try to share SSL contexts across multiple connections + in <application>libpq</> (Heikki Linnakangas) + </para> + + <para> + This led to assorted corner-case bugs, particularly when trying to use + different SSL parameters for different connections. + </para> + </listitem> + + <listitem> + <para> + Avoid corner-case memory leak in <application>libpq</> (Tom Lane) + </para> + + <para> + The reported problem involved leaking an error report + during <function>PQreset()</>, but there might be related cases. + </para> + </listitem> + + <listitem> +<!-- +Author: Heikki Linnakangas <[email protected]> +Branch: master [3fcc98c99] 2016-09-18 13:46:32 +0300 +Branch: REL9_6_STABLE Release: REL9_6_0 [e06728d63] 2016-09-18 13:56:11 +0300 +Branch: REL9_5_STABLE [7c177ddc2] 2016-09-18 13:56:52 +0300 +Branch: REL9_4_STABLE [d48e10a68] 2016-09-18 13:59:57 +0300 +Branch: REL9_3_STABLE [b31f335bf] 2016-09-18 14:00:10 +0300 +Branch: REL9_2_STABLE [a4a3fac16] 2016-09-18 14:00:13 +0300 +Branch: REL9_1_STABLE [ed29d2de2] 2016-09-18 14:07:30 +0300 +--> + <para> + Make <application>ecpg</>'s <option>--help</> and <option>--version</> + options work consistently with our other executables (Haribabu Kommi) + </para> + </listitem> + + <listitem> +<!-- +Author: Heikki Linnakangas <[email protected]> +Branch: master [40c3fe498] 2016-09-19 22:55:43 +0300 +Branch: REL9_6_STABLE Release: REL9_6_0 [f65764a04] 2016-09-19 22:55:50 +0300 +Branch: REL9_5_STABLE [edb5c4097] 2016-09-19 22:58:03 +0300 +Branch: REL9_4_STABLE [476945c45] 2016-09-19 22:59:44 +0300 +Branch: master [65c655638] 2016-09-21 13:14:48 +0300 +Branch: REL9_6_STABLE Release: REL9_6_0 [93834a20f] 2016-09-21 13:16:02 +0300 +Branch: REL9_5_STABLE [b93d37474] 2016-09-21 13:16:20 +0300 +Branch: REL9_4_STABLE [f16d4a241] 2016-09-21 13:16:24 +0300 +--> + <para> + Fix <application>pgbench</>'s calculation of average latency + (Fabien Coelho) + </para> + + <para> + The calculation was incorrect when there were <literal>\sleep</> + commands in the script, or when the test duration was specified in + number of transactions rather than total time. + </para> + </listitem> + + <listitem> + <para> + In <application>pg_upgrade</>, check library loadability in name order + (Tom Lane) + </para> + + <para> + This is a workaround to deal with cross-extension dependencies from + language transform modules to their base language and data type + modules. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [12f6eadff] 2016-09-23 13:49:26 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [7e02476f3] 2016-09-23 13:49:26 -0400 +Branch: REL9_5_STABLE [96e16d739] 2016-09-23 13:49:26 -0400 +Branch: REL9_4_STABLE [912ea1945] 2016-09-23 13:49:27 -0400 +Branch: REL9_3_STABLE [f39bb487d] 2016-09-23 13:49:27 -0400 +Branch: REL9_2_STABLE [53b29d986] 2016-09-23 13:49:27 -0400 +--> + <para> + In <application>pg_dump</>, never dump range constructor functions + (Tom Lane) + </para> + + <para> + This oversight led to <application>pg_upgrade</> failures with + extensions containing range types, due to duplicate creation of the + constructor functions. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [e97e9c57b] 2016-09-08 10:48:03 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [a88cee90f] 2016-09-08 10:48:03 -0400 +Branch: REL9_5_STABLE [142a110b3] 2016-09-08 10:48:03 -0400 +--> + <para> + In <application>pg_dump</> with <option>-C</>, + suppress <literal>TABLESPACE</> clause of <command>CREATE DATABASE</> + if <option>--no-tablespaces</> is specified (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Simon Riggs <[email protected]> +Branch: master [49340627f] 2016-08-29 12:16:18 +0100 +Branch: REL9_6_STABLE Release: REL9_6_0 [216fd7fe7] 2016-08-29 12:18:12 +0100 +Branch: REL9_5_STABLE [9050e5c89] 2016-08-29 12:18:57 +0100 +Branch: REL9_5_STABLE [3aa233f82] 2016-08-29 18:12:04 -0300 +--> + <para> + Make <application>pg_receivexlog</> work correctly + with <option>--synchronous</> without slots (Gabriele Bartolini) + </para> + </listitem> + + <listitem> + <para> + Disallow specifying both <option>--source-server</> + and <option>--source-target</> options to <application>pg_rewind</> + (Michael Banck) + </para> + </listitem> + + <listitem> + <para> + Make <application>pg_rewind</> turn off <varname>synchronous_commit</> + in its session on the source server (Michael Banck, Michael Paquier) + </para> + + <para> + This allows <application>pg_rewind</> to work even when the source + server is using synchronous replication that is not working for some + reason. + </para> + </listitem> + + <listitem> + <para> + In <application>pg_xlogdump</>, retry opening new WAL segments when + using <option>--follow</> option (Magnus Hagander) + </para> + + <para> + This allows for a possible delay in the server's creation of the next + segment. + </para> + </listitem> + + <listitem> +<!-- +Author: Fujii Masao <[email protected]> +Branch: master [bab7823a4] 2016-08-29 14:34:58 +0900 +Branch: REL9_6_STABLE Release: REL9_6_0 [2802b02a5] 2016-08-29 14:35:40 +0900 +Branch: REL9_5_STABLE [7dfb9b479] 2016-08-29 14:35:51 +0900 +Branch: REL9_4_STABLE [314a25fb3] 2016-08-29 14:38:17 +0900 +Branch: REL9_3_STABLE [5833306dd] 2016-08-29 15:51:30 +0900 +--> + <para> + Fix <application>pg_xlogdump</> to cope with a WAL file that begins + with a continuation record spanning more than one page (Pavan + Deolasee) + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [8a503526e] 2016-09-15 09:30:38 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [bea38f34a] 2016-09-15 09:30:37 -0400 +Branch: REL9_5_STABLE [60b6d99da] 2016-09-15 09:30:36 -0400 +Branch: REL9_4_STABLE [1336bd986] 2016-09-15 09:22:52 -0400 +--> + <para> + Fix <filename>contrib/pg_buffercache</> to work + when <varname>shared_buffers</> exceeds 256GB (KaiGai Kohei) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [6657acc01] 2016-08-17 15:51:10 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [d715b76d1] 2016-08-17 15:51:10 -0400 +Branch: REL9_5_STABLE [509815ed7] 2016-08-17 15:51:10 -0400 +Branch: REL9_4_STABLE [3fa8ec44d] 2016-08-17 15:51:10 -0400 +Branch: REL9_3_STABLE [7baa8bfca] 2016-08-17 15:51:10 -0400 +Branch: REL9_2_STABLE [60bb1bb12] 2016-08-17 15:51:11 -0400 +Branch: REL9_1_STABLE [9942376a5] 2016-08-17 15:51:11 -0400 +--> + <para> + Fix <filename>contrib/intarray/bench/bench.pl</> to print the results + of the <command>EXPLAIN</> it does when given the <option>-e</> option + (Daniel Gustafsson) + </para> + </listitem> + + <listitem> +<!-- +Author: Heikki Linnakangas <[email protected]> +Branch: master [593d4e47d] 2016-09-15 14:42:29 +0300 +Branch: REL9_6_STABLE Release: REL9_6_0 [fcd93e4af] 2016-09-15 12:55:38 +0300 +Branch: REL9_5_STABLE [e2838c580] 2016-09-15 14:51:42 +0300 +Branch: master [5c6df67e0] 2016-09-15 22:52:51 +0300 +Branch: REL9_6_STABLE Release: REL9_6_0 [9895818d5] 2016-09-15 22:45:08 +0300 +Branch: REL9_5_STABLE [48e5ba61e] 2016-09-15 22:38:01 +0300 +--> + <para> + Support OpenSSL 1.1.0 (Heikki Linnakangas) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [c3a081846] 2016-09-23 15:50:00 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [5a83e2d4e] 2016-09-23 15:50:00 -0400 +Branch: REL9_5_STABLE [025c9a722] 2016-09-23 15:50:00 -0400 +Branch: REL9_4_STABLE [5d41f27a9] 2016-09-23 15:50:00 -0400 +--> + <para> + Install TAP test infrastructure so that it's available for extension + testing (Craig Ringer) + </para> + + <para> + When <productname>PostgreSQL</> has been configured + with <option>--enable-tap-tests</>, <quote>make install</> will now + install the Perl support files for TAP testing where PGXS can find + them. This allows non-core extensions to + use <literal>$(prove_check)</> without extra tests. + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [8614b39bc] 2016-09-19 14:25:57 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [156f974f5] 2016-09-19 14:27:04 -0400 +Branch: REL9_5_STABLE [52acf020a] 2016-09-19 14:27:08 -0400 +Branch: REL9_4_STABLE [ca93b816f] 2016-09-19 14:27:13 -0400 +--> + <para> + In MSVC builds, include <application>pg_recvlogical</> in a + client-only installation (MauMau) + </para> + </listitem> + + <listitem> +<!-- +Author: Magnus Hagander <[email protected]> +Branch: master [a79a68562] 2016-08-18 12:32:42 +0200 +Branch: REL9_6_STABLE Release: REL9_6_0 [191d45793] 2016-08-18 12:37:55 +0200 +Branch: REL9_5_STABLE [a0833b972] 2016-08-18 15:35:12 +0200 +Branch: REL9_4_STABLE [1d990cd8c] 2016-08-18 15:35:26 +0200 +Branch: REL9_3_STABLE [e8aed974b] 2016-08-18 15:35:36 +0200 +Branch: REL9_2_STABLE [35982db49] 2016-08-18 15:35:43 +0200 +--> + <para> + Update Windows time zone mapping to recognize some time zone names + added in recent Windows versions (Michael Paquier) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [39b691f25] 2016-09-02 17:30:02 -0400 +Branch: REL9_6_STABLE Release: REL9_6_0 [32c9950b3] 2016-09-02 17:29:31 -0400 +Branch: REL9_5_STABLE [73a802a41] 2016-09-02 17:29:31 -0400 +Branch: REL9_4_STABLE [7430ac852] 2016-09-02 17:29:32 -0400 +Branch: REL9_3_STABLE [ee78d4885] 2016-09-02 17:29:32 -0400 +Branch: REL9_2_STABLE [1195b8efe] 2016-09-02 17:29:32 -0400 +Branch: REL9_1_STABLE [380dad29d] 2016-09-02 17:29:32 -0400 +--> + <para> + Prevent failure of obsolete dynamic time zone abbreviations (Tom Lane) + </para> + + <para> + If a dynamic time zone abbreviation does not match any entry in the + referenced time zone, treat it as equivalent to the time zone name. + This avoids unexpected failures when IANA removes abbreviations from + their time zone database, as they did in <application>tzdata</> + release 2016f and seem likely to do again in the future. The + consequences were not limited to not recognizing the individual + abbreviation; any mismatch caused + the <structname>pg_timezone_abbrevs</> view to fail altogether. + </para> + </listitem> + + <listitem> + <para> + Update time zone data files to <application>tzdata</> release 2016h + for DST law changes in Palestine and Turkey, plus historical + corrections for Turkey and some regions of Russia. + Switch to numeric abbreviations for some time zones in Antarctica, + the former Soviet Union, and Sri Lanka. + </para> + + <para> + The IANA time zone database previously provided textual abbreviations + for all time zones, sometimes making up abbreviations that have little + or no currency among the local population. They are in process of + reversing that policy in favor of using numeric UTC offsets in zones + where there is no evidence of real-world use of an English + abbreviation. At least for the time being, <productname>PostgreSQL</> + will continue to accept such removed abbreviations for timestamp input. + But they will not be shown in the <structname>pg_timezone_names</> + view nor used for output. + </para> + + <para> + In this update, <literal>AMT</> is no longer shown as being in use to + mean Armenia Time. Therefore, we have changed the <literal>Default</> + abbreviation set to interpret it as Amazon Time, thus UTC-4 not UTC+4. + </para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + <sect1 id="release-9-5-4"> <title>Release 9.5.4</title> - <note> - <title>Release Date</title> - <simpara>2016-08-11</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-08-11</para> + </formalpara> <para> This release contains a variety of fixes from 9.5.3. @@ -1077,10 +3200,10 @@ Branch: REL9_1_STABLE [a44388ffe] 2016-08-05 12:59:02 -0400 <sect1 id="release-9-5-3"> <title>Release 9.5.3</title> - <note> - <title>Release Date</title> - <simpara>2016-05-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-05-12</para> + </formalpara> <para> This release contains a variety of fixes from 9.5.2. @@ -1578,10 +3701,10 @@ Branch: REL9_1_STABLE [bfc39da64] 2016-05-05 20:09:32 -0400 <sect1 id="release-9-5-2"> <title>Release 9.5.2</title> - <note> - <title>Release Date</title> - <simpara>2016-03-31</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-03-31</para> + </formalpara> <para> This release contains a variety of fixes from 9.5.1. @@ -2023,7 +4146,7 @@ Branch: REL9_1_STABLE [e56acbe2a] 2016-02-10 19:30:12 -0500 <para> This dodges a portability problem on FreeBSD-derived platforms - (including OS X). + (including macOS). </para> </listitem> @@ -2289,10 +4412,10 @@ Branch: REL9_1_STABLE [e5fd35cc5] 2016-03-25 19:03:54 -0400 <sect1 id="release-9-5-1"> <title>Release 9.5.1</title> - <note> - <title>Release Date</title> - <simpara>2016-02-11</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-02-11</para> + </formalpara> <para> This release contains a variety of fixes from 9.5.0. @@ -2737,10 +4860,10 @@ Branch: REL9_1_STABLE [6887d72d0] 2016-02-05 10:59:39 -0500 <sect1 id="release-9-5"> <title>Release 9.5</title> - <note> - <title>Release Date</title> - <simpara>2016-01-07</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-01-07</para> + </formalpara> <sect2> <title>Overview</title> @@ -4779,7 +6902,7 @@ Add GUC and storage parameter to set the maximum size of GIN pending list. linkend="pgarchivecleanup"><application>pg_archivecleanup</></>, <link linkend="pgtestfsync"><application>pg_test_fsync</></>, <link linkend="pgtesttiming"><application>pg_test_timing</></>, - and <link linkend="pgxlogdump"><application>pg_xlogdump</></> + and <link linkend="pgwaldump"><application>pg_xlogdump</></> from <filename>contrib</> to <filename>src/bin</> (Peter Eisentraut) </para> @@ -4806,7 +6929,7 @@ Add GUC and storage parameter to set the maximum size of GIN pending list. --> <para> Allow <link - linkend="app-pgreceivexlog"><application>pg_receivexlog</></> + linkend="app-pgreceivewal"><application>pg_receivexlog</></> to manage physical replication slots (Michael Paquier) </para> @@ -4822,7 +6945,7 @@ Add GUC and storage parameter to set the maximum size of GIN pending list. --> <para> Allow <link - linkend="app-pgreceivexlog"><application>pg_receivexlog</></> + linkend="app-pgreceivewal"><application>pg_receivexlog</></> to synchronously flush <acronym>WAL</> to storage using new <option>--synchronous</> option (Furuya Osamu, Fujii Masao) </para> @@ -4882,7 +7005,7 @@ Add GUC and storage parameter to set the maximum size of GIN pending list. 2014-09-19 [bdd5726] Andres..: Add the capability to display summary statistic.. --> <para> - Add <link linkend="pgxlogdump"><application>pg_xlogdump</></> option + Add <link linkend="pgwaldump"><application>pg_xlogdump</></> option <option>--stats</> to display summary statistics (Abhijit Menon-Sen) </para> </listitem> diff --git a/doc/src/sgml/release-9.6.sgml b/doc/src/sgml/release-9.6.sgml index cc886fa2bb..764f812d60 100644 --- a/doc/src/sgml/release-9.6.sgml +++ b/doc/src/sgml/release-9.6.sgml @@ -1,14 +1,3145 @@ <!-- doc/src/sgml/release-9.6.sgml --> <!-- See header comment in release.sgml about typical markup --> + <sect1 id="release-9-6-3"> + <title>Release 9.6.3</title> + + <formalpara> + <title>Release date:</title> + <para>2017-05-11</para> + </formalpara> + + <para> + This release contains a variety of fixes from 9.6.2. + For information about new features in the 9.6 major release, see + <xref linkend="release-9-6">. + </para> + + <sect2> + <title>Migration to Version 9.6.3</title> + + <para> + A dump/restore is not required for those running 9.6.X. + </para> + + <para> + However, if you use foreign data servers that make use of user + passwords for authentication, see the first changelog entry below. + </para> + + <para> + Also, if you are using third-party replication tools that depend + on <quote>logical decoding</>, see the fourth changelog entry below. + </para> + + <para> + Also, if you are upgrading from a version earlier than 9.6.2, + see <xref linkend="release-9-6-2">. + </para> + </sect2> + + <sect2> + <title>Changes</title> + + <itemizedlist> + + <listitem> +<!-- +Author: Noah Misch <[email protected]> +Branch: master [3eefc5105] 2017-05-08 07:24:24 -0700 +Branch: REL9_6_STABLE [c928addfc] 2017-05-08 07:24:27 -0700 +Branch: REL9_5_STABLE [db2158108] 2017-05-08 07:24:27 -0700 +Branch: REL9_4_STABLE [b2423f0fa] 2017-05-08 07:24:27 -0700 +Branch: REL9_3_STABLE [b5b124046] 2017-05-08 07:24:28 -0700 +Branch: REL9_2_STABLE [99cbb0bd9] 2017-05-08 07:24:28 -0700 +--> + <para> + Restrict visibility + of <structname>pg_user_mappings</>.<structfield>umoptions</>, to + protect passwords stored as user mapping options + (Michael Paquier, Feike Steenbergen) + </para> + + <para> + The previous coding allowed the owner of a foreign server object, + or anyone he has granted server <literal>USAGE</> permission to, + to see the options for all user mappings associated with that server. + This might well include passwords for other users. + Adjust the view definition to match the behavior of + <structname>information_schema.user_mapping_options</>, namely that + these options are visible to the user being mapped, or if the mapping + is for <literal>PUBLIC</literal> and the current user is the server + owner, or if the current user is a superuser. + (CVE-2017-7486) + </para> + + <para> + By itself, this patch will only fix the behavior in newly initdb'd + databases. If you wish to apply this change in an existing database, + you will need to do the following: + </para> + + <procedure> + <step> + <para> + Restart the postmaster after adding <literal>allow_system_table_mods + = true</> to <filename>postgresql.conf</>. (In versions + supporting <command>ALTER SYSTEM</>, you can use that to make the + configuration change, but you'll still need a restart.) + </para> + </step> + + <step> + <para> + In <emphasis>each</> database of the cluster, + run the following commands as superuser: +<programlisting> +SET search_path = pg_catalog; +CREATE OR REPLACE VIEW pg_user_mappings AS + SELECT + U.oid AS umid, + S.oid AS srvid, + S.srvname AS srvname, + U.umuser AS umuser, + CASE WHEN U.umuser = 0 THEN + 'public' + ELSE + A.rolname + END AS usename, + CASE WHEN (U.umuser <> 0 AND A.rolname = current_user) + OR (U.umuser = 0 AND pg_has_role(S.srvowner, 'USAGE')) + OR (SELECT rolsuper FROM pg_authid WHERE rolname = current_user) + THEN U.umoptions + ELSE NULL END AS umoptions + FROM pg_user_mapping U + LEFT JOIN pg_authid A ON (A.oid = U.umuser) JOIN + pg_foreign_server S ON (U.umserver = S.oid); +</programlisting> + </para> + </step> + + <step> + <para> + Do not forget to include the <literal>template0</> + and <literal>template1</> databases, or the vulnerability will still + exist in databases you create later. To fix <literal>template0</>, + you'll need to temporarily make it accept connections. + In <productname>PostgreSQL</> 9.5 and later, you can use +<programlisting> +ALTER DATABASE template0 WITH ALLOW_CONNECTIONS true; +</programlisting> + and then after fixing <literal>template0</>, undo that with +<programlisting> +ALTER DATABASE template0 WITH ALLOW_CONNECTIONS false; +</programlisting> + In prior versions, instead use +<programlisting> +UPDATE pg_database SET datallowconn = true WHERE datname = 'template0'; +UPDATE pg_database SET datallowconn = false WHERE datname = 'template0'; +</programlisting> + </para> + </step> + + <step> + <para> + Finally, remove the <literal>allow_system_table_mods</> configuration + setting, and again restart the postmaster. + </para> + </step> + </procedure> + </listitem> + + <listitem> +<!-- +Author: Peter Eisentraut <[email protected]> +Branch: master [e2d4ef8de] 2017-05-08 09:26:32 -0400 +Branch: REL9_6_STABLE [c33c42362] 2017-05-08 09:18:57 -0400 +Branch: REL9_5_STABLE [d45cd7c0e] 2017-05-08 09:19:07 -0400 +Branch: REL9_4_STABLE [3e5ea1f9b] 2017-05-08 09:19:15 -0400 +Branch: REL9_3_STABLE [4f1b2089a] 2017-05-08 09:19:23 -0400 +Branch: REL9_2_STABLE [d035c1b97] 2017-05-08 09:19:42 -0400 +Author: Tom Lane <[email protected]> +Branch: master [b6576e591] 2017-05-08 11:18:40 -0400 +Branch: REL9_6_STABLE [cad159432] 2017-05-08 11:18:54 -0400 +Branch: REL9_5_STABLE [a199582ef] 2017-05-08 11:19:00 -0400 +Branch: REL9_4_STABLE [d3f3f9568] 2017-05-08 11:19:04 -0400 +Branch: REL9_3_STABLE [703da1795] 2017-05-08 11:19:08 -0400 +--> + <para> + Prevent exposure of statistical information via leaky operators + (Peter Eisentraut) + </para> + + <para> + Some selectivity estimation functions in the planner will apply + user-defined operators to values obtained + from <structname>pg_statistic</>, such as most common values and + histogram entries. This occurs before table permissions are checked, + so a nefarious user could exploit the behavior to obtain these values + for table columns he does not have permission to read. To fix, + fall back to a default estimate if the operator's implementation + function is not certified leak-proof and the calling user does not have + permission to read the table column whose statistics are needed. + At least one of these criteria is satisfied in most cases in practice. + (CVE-2017-7484) + </para> + </listitem> + + <listitem> +<!-- +Author: Noah Misch <[email protected]> +Branch: master [0170b10df] 2017-05-08 07:24:24 -0700 +Branch: REL9_6_STABLE [aafbd1df9] 2017-05-08 07:24:27 -0700 +Branch: REL9_5_STABLE [96d745492] 2017-05-08 07:24:27 -0700 +Branch: REL9_4_STABLE [ed36c1fe1] 2017-05-08 07:24:27 -0700 +Branch: REL9_3_STABLE [3eab81127] 2017-05-08 07:24:28 -0700 +--> + <para> + Restore <application>libpq</>'s recognition of + the <envar>PGREQUIRESSL</> environment variable (Daniel Gustafsson) + </para> + + <para> + Processing of this environment variable was unintentionally dropped + in <productname>PostgreSQL</> 9.3, but its documentation remained. + This creates a security hazard, since users might be relying on the + environment variable to force SSL-encrypted connections, but that + would no longer be guaranteed. Restore handling of the variable, + but give it lower priority than <envar>PGSSLMODE</>, to avoid + breaking configurations that work correctly with post-9.3 code. + (CVE-2017-7485) + </para> + </listitem> + + <listitem> +<!-- +Author: Andres Freund <[email protected]> +Branch: master [2bef06d51] 2017-04-27 13:13:36 -0700 +Branch: REL9_6_STABLE [28afff347] 2017-04-27 13:13:36 -0700 +Branch: REL9_5_STABLE [47f896b5c] 2017-04-27 13:13:37 -0700 +Branch: REL9_4_STABLE [5da646138] 2017-04-27 13:13:37 -0700 +Branch: master [56e19d938] 2017-04-27 15:29:15 -0700 +Branch: REL9_6_STABLE [29e8c881d] 2017-04-27 15:29:33 -0700 +Branch: REL9_5_STABLE [54270d7eb] 2017-04-27 15:29:43 -0700 +Branch: REL9_4_STABLE [b6ecf26cc] 2017-04-27 15:29:52 -0700 +--> + <para> + Fix possibly-invalid initial snapshot during logical decoding + (Petr Jelinek, Andres Freund) + </para> + + <para> + The initial snapshot created for a logical decoding replication slot + was potentially incorrect. This could cause third-party tools that + use logical decoding to copy incomplete/inconsistent initial data. + This was more likely to happen if the source server was busy at the + time of slot creation, or if another logical slot already existed. + </para> + + <para> + If you are using a replication tool that depends on logical decoding, + and it should have copied a nonempty data set at the start of + replication, it is advisable to recreate the replica after + installing this update, or to verify its contents against the source + server. + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [87f998203] 2017-03-14 11:51:11 -0400 +Branch: REL9_6_STABLE [36fcb36b8] 2017-03-14 11:52:27 -0400 +Branch: REL9_5_STABLE [c17a3f57e] 2017-03-14 12:03:29 -0400 +Branch: REL9_4_STABLE [bbd5e600f] 2017-03-14 12:06:36 -0400 +Branch: REL9_3_STABLE [6bd7816e7] 2017-03-14 12:08:14 -0400 +Branch: REL9_2_STABLE [b2ae1d6c4] 2017-03-14 12:10:36 -0400 +--> + <para> + Fix possible corruption of <quote>init forks</> of unlogged indexes + (Robert Haas, Michael Paquier) + </para> + + <para> + This could result in an unlogged index being set to an invalid state + after a crash and restart. Such a problem would persist until the + index was dropped and rebuilt. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [0874d4f3e] 2017-04-23 13:11:06 -0400 +Branch: REL9_6_STABLE [f5885488d] 2017-04-23 13:11:08 -0400 +Branch: REL9_5_STABLE [a66e01bbc] 2017-04-23 13:10:57 -0400 +Branch: REL9_4_STABLE [2e14541c4] 2017-04-23 13:10:57 -0400 +Branch: REL9_3_STABLE [856580873] 2017-04-23 13:10:57 -0400 +Branch: REL9_2_STABLE [952e33b05] 2017-04-23 13:10:58 -0400 +--> + <para> + Fix incorrect reconstruction of <structname>pg_subtrans</> entries + when a standby server replays a prepared but uncommitted two-phase + transaction (Tom Lane) + </para> + + <para> + In most cases this turned out to have no visible ill effects, but in + corner cases it could result in circular references + in <structname>pg_subtrans</>, potentially causing infinite loops + in queries that examine rows modified by the two-phase transaction. + </para> + </listitem> + + <listitem> +<!-- +Author: Fujii Masao <[email protected]> +Branch: master [1d04a59be] 2017-02-22 03:11:58 +0900 +Branch: REL9_6_STABLE [9fab155c6] 2017-02-22 08:29:32 +0900 +Branch: REL9_5_STABLE [feb659cce] 2017-02-22 08:29:44 +0900 +Branch: REL9_4_STABLE [a3eb715a3] 2017-02-22 08:29:57 +0900 +--> + <para> + Avoid possible crash in <application>walsender</> due to failure + to initialize a string buffer (Stas Kelvich, Fujii Masao) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [3f074845a] 2017-05-04 13:59:39 -0400 +Branch: REL9_6_STABLE [855f0e924] 2017-05-04 13:59:13 -0400 +Branch: REL9_5_STABLE [6cfb428b0] 2017-05-04 13:59:13 -0400 +--> + <para> + Fix possible crash when rescanning a nearest-neighbor index-only scan + on a GiST index (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [893902085] 2017-04-24 13:00:30 -0400 +Branch: REL9_6_STABLE [dfa4baf91] 2017-04-24 13:00:23 -0400 +Branch: master [aa1351f1e] 2017-04-26 16:17:34 -0400 +Branch: REL9_6_STABLE [e880df25e] 2017-04-26 16:17:29 -0400 +--> + <para> + Prevent delays in postmaster's launching of multiple parallel worker + processes (Tom Lane) + </para> + + <para> + There could be a significant delay (up to tens of seconds) before + satisfying a query's request for more than one worker process, or when + multiple queries requested workers simultaneously. On most platforms + this required unlucky timing, but on some it was the typical case. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [4fe04244b] 2017-04-24 12:16:58 -0400 +Branch: REL9_6_STABLE [63f64d282] 2017-04-24 12:16:58 -0400 +Branch: REL9_5_STABLE [dba1f310a] 2017-04-24 12:16:58 -0400 +Branch: REL9_4_STABLE [436b560b8] 2017-04-24 12:16:58 -0400 +--> + <para> + Fix postmaster's handling of <function>fork()</> failure for a + background worker process (Tom Lane) + </para> + + <para> + Previously, the postmaster updated portions of its state as though + the process had been launched successfully, resulting in subsequent + confusion. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [89deca582] 2017-04-07 12:18:38 -0400 +Branch: REL9_6_STABLE [c0a493e17] 2017-04-07 12:18:38 -0400 +--> + <para> + Fix possible <quote>no relation entry for relid 0</> error when + planning nested set operations (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [1ea60ad60] 2017-03-15 12:28:54 -0400 +Branch: REL9_6_STABLE [5feb78ae8] 2017-03-15 12:41:00 -0400 +Branch: master [f120b614e] 2017-03-24 12:30:39 -0400 +Branch: REL9_6_STABLE [5674a258f] 2017-03-24 12:39:07 -0400 +Branch: master [7d8f6986b] 2017-03-31 21:01:20 -0400 +Branch: REL9_6_STABLE [fb1879c37] 2017-03-31 21:10:30 -0400 +--> + <para> + Fix assorted minor issues in planning of parallel queries (Robert Haas) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [76799fc89] 2017-04-17 15:29:15 -0400 +Branch: REL9_6_STABLE [6c73b390b] 2017-04-17 15:29:00 -0400 +Branch: REL9_5_STABLE [6f0f98bb0] 2017-04-17 15:29:00 -0400 +--> + <para> + Avoid applying <quote>physical targetlist</> optimization to custom + scans (Dmitry Ivanov, Tom Lane) + </para> + + <para> + This optimization supposed that retrieving all columns of a tuple + is inexpensive, which is true for ordinary Postgres tuples; but it + might not be the case for a custom scan provider. + </para> + </listitem> + + <listitem> +<!-- +Author: Stephen Frost <[email protected]> +Branch: master [aa5d3c0b3] 2017-05-06 21:46:35 -0400 +Branch: REL9_6_STABLE [92b15224b] 2017-05-06 21:46:41 -0400 +Branch: REL9_5_STABLE [d617c7629] 2017-05-06 21:46:56 -0400 +--> + <para> + Use the correct sub-expression when applying a <literal>FOR ALL</> + row-level-security policy (Stephen Frost) + </para> + + <para> + In some cases the <literal>WITH CHECK</> restriction would be applied + when the <literal>USING</> restriction is more appropriate. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [9209e0760] 2017-05-02 18:06:09 -0400 +Branch: REL9_6_STABLE [d56b8b41b] 2017-05-02 18:05:54 -0400 +Branch: REL9_5_STABLE [d0d3a57bf] 2017-05-02 18:05:54 -0400 +Branch: REL9_4_STABLE [c6b3d0706] 2017-05-02 18:05:54 -0400 +Branch: REL9_3_STABLE [062824edd] 2017-05-02 18:05:54 -0400 +Branch: REL9_2_STABLE [c9d6c564f] 2017-05-02 18:05:54 -0400 +--> + <para> + Ensure parsing of queries in extension scripts sees the results of + immediately-preceding DDL (Julien Rouhaud, Tom Lane) + </para> + + <para> + Due to lack of a cache flush step between commands in an extension + script file, non-utility queries might not see the effects of an + immediately preceding catalog change, such as <command>ALTER TABLE + ... RENAME</>. + </para> + </listitem> + + <listitem> +<!-- +Author: Noah Misch <[email protected]> +Branch: master [f30f34e58] 2017-02-12 16:03:41 -0500 +Branch: REL9_6_STABLE [4d43d5d35] 2017-02-12 16:03:46 -0500 +Branch: REL9_5_STABLE [660e457f5] 2017-02-12 16:03:54 -0500 +Branch: REL9_4_STABLE [804aad8ff] 2017-02-12 16:04:09 -0500 +Branch: REL9_3_STABLE [b167d57d5] 2017-02-12 16:05:12 -0500 +Branch: REL9_2_STABLE [27a8c8033] 2017-02-12 16:05:23 -0500 +--> + <para> + Skip tablespace privilege checks when <command>ALTER TABLE ... ALTER + COLUMN TYPE</> rebuilds an existing index (Noah Misch) + </para> + + <para> + The command failed if the calling user did not currently have + <literal>CREATE</> privilege for the tablespace containing the index. + That behavior seems unhelpful, so skip the check, allowing the + index to be rebuilt where it is. + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [6a4dda44e] 2017-04-28 14:48:38 -0400 +Branch: REL9_6_STABLE [8a9c83bfa] 2017-04-28 14:48:44 -0400 +Branch: REL9_5_STABLE [a0291c330] 2017-04-28 14:50:36 -0400 +Branch: REL9_4_STABLE [93a07a68e] 2017-04-28 14:52:20 -0400 +Branch: REL9_3_STABLE [954744f7a] 2017-04-28 14:53:56 -0400 +Branch: REL9_2_STABLE [f60f0c8fe] 2017-04-28 14:55:42 -0400 +--> + <para> + Fix <command>ALTER TABLE ... VALIDATE CONSTRAINT</> to not recurse + to child tables when the constraint is marked <literal>NO INHERIT</> + (Amit Langote) + </para> + + <para> + This fix prevents unwanted <quote>constraint does not exist</> failures + when no matching constraint is present in the child tables. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [a8df75b0a] 2017-03-06 16:50:47 -0500 +Branch: REL9_6_STABLE [943140d57] 2017-03-06 16:50:47 -0500 +Branch: REL9_5_STABLE [420d9ec0a] 2017-03-06 16:50:47 -0500 +--> + <para> + Avoid dangling pointer in <command>COPY ... TO</> when row-level + security is active for the source table (Tom Lane) + </para> + + <para> + Usually this had no ill effects, but sometimes it would cause + unexpected errors or crashes. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [dbca84f04] 2017-03-04 16:09:33 -0500 +Branch: REL9_6_STABLE [68f7b91e5] 2017-03-04 16:09:33 -0500 +Branch: REL9_5_STABLE [807df31d1] 2017-03-04 16:09:33 -0500 +--> + <para> + Avoid accessing an already-closed relcache entry in <command>CLUSTER</> + and <command>VACUUM FULL</> (Tom Lane) + </para> + + <para> + With some bad luck, this could lead to indexes on the target + relation getting rebuilt with the wrong persistence setting. + </para> + </listitem> + + <listitem> +<!-- +Author: Andrew Gierth <[email protected]> +Branch: master [1914c5ea7] 2017-03-16 22:28:03 +0000 +Branch: REL9_6_STABLE [9b626f6c3] 2017-03-16 22:31:49 +0000 +Branch: REL9_5_STABLE [ee78ad5bc] 2017-03-16 22:33:59 +0000 +Branch: REL9_4_STABLE [269efd052] 2017-03-16 22:32:56 +0000 +Branch: REL9_3_STABLE [8f8a5aefc] 2017-03-16 22:33:18 +0000 +Branch: REL9_2_STABLE [a494ff4b0] 2017-03-16 22:33:38 +0000 +Branch: master [64ae420b2] 2017-03-17 14:35:54 +0000 +Branch: REL9_6_STABLE [733488dc6] 2017-03-17 14:46:15 +0000 +--> + <para> + Fix <command>VACUUM</> to account properly for pages that could not + be scanned due to conflicting page pins (Andrew Gierth) + </para> + + <para> + This tended to lead to underestimation of the number of tuples in + the table. In the worst case of a small heavily-contended + table, <command>VACUUM</> could incorrectly report that the table + contained no tuples, leading to very bad planning choices. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [f2ec57dee] 2017-02-15 16:40:05 -0500 +Branch: REL9_6_STABLE [354dfa235] 2017-02-15 16:40:05 -0500 +Branch: REL9_5_STABLE [96ba17640] 2017-02-15 16:40:06 -0500 +Branch: REL9_4_STABLE [d0e9c0e31] 2017-02-15 16:40:06 -0500 +Branch: REL9_3_STABLE [6a4941f8c] 2017-02-15 16:40:06 -0500 +Branch: REL9_2_STABLE [030705e4f] 2017-02-15 16:40:06 -0500 +--> + <para> + Ensure that bulk-tuple-transfer loops within a hash join are + interruptible by query cancel requests (Tom Lane, Thomas Munro) + </para> + </listitem> + + <listitem> +<!-- +Author: Teodor Sigaev <[email protected]> +Branch: master [d5286aa90] 2017-03-21 16:23:10 +0300 +Branch: REL9_6_STABLE [a4d07d2e9] 2017-03-21 16:24:10 +0300 +--> + <para> + Fix incorrect support for certain <type>box</> operators in SP-GiST + (Nikita Glukhov) + </para> + + <para> + SP-GiST index scans using the operators <literal>&<</> + <literal>&></> <literal>&<|</> and <literal>|&></> + would yield incorrect answers. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [df1a699e5] 2017-04-05 23:51:27 -0400 +Branch: REL9_6_STABLE [fd52b8834] 2017-04-05 23:51:28 -0400 +Branch: REL9_5_STABLE [d68a2b20a] 2017-04-05 23:51:28 -0400 +Branch: REL9_4_STABLE [8851bcf88] 2017-04-05 23:51:28 -0400 +--> + <para> + Fix integer-overflow problems in <type>interval</> comparison (Kyotaro + Horiguchi, Tom Lane) + </para> + + <para> + The comparison operators for type <type>interval</> could yield wrong + answers for intervals larger than about 296000 years. Indexes on + columns containing such large values should be reindexed, since they + may be corrupt. + </para> + </listitem> + + <listitem> +<!-- +Author: Peter Eisentraut <[email protected]> +Branch: master [0de791ed7] 2017-05-03 21:41:10 -0400 +Branch: REL9_6_STABLE [071d13395] 2017-05-04 21:17:46 -0400 +Branch: REL9_5_STABLE [9750a9583] 2017-05-04 21:20:26 -0400 +Branch: REL9_4_STABLE [12dd58d64] 2017-05-04 21:22:48 -0400 +Branch: REL9_3_STABLE [6e86b448f] 2017-05-04 21:31:12 -0400 +Branch: REL9_2_STABLE [a48d47908] 2017-05-04 22:39:23 -0400 +--> + <para> + Fix <function>cursor_to_xml()</> to produce valid output + with <replaceable>tableforest</> = false + (Thomas Munro, Peter Eisentraut) + </para> + + <para> + Previously it failed to produce a wrapping <literal><table></> + element. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [8f93bd851] 2017-02-08 18:04:59 -0500 +Branch: REL9_6_STABLE [404756fe8] 2017-02-08 18:04:59 -0500 +Branch: REL9_5_STABLE [7786b9848] 2017-02-08 18:04:59 -0500 +Branch: REL9_4_STABLE [1888fad44] 2017-02-08 18:04:59 -0500 +Branch: master [5d2adf0f8] 2017-02-09 15:50:16 -0500 +Branch: REL9_6_STABLE [fc96a5fbc] 2017-02-09 15:49:57 -0500 +Branch: REL9_5_STABLE [cf73c6bfc] 2017-02-09 15:49:57 -0500 +Branch: REL9_4_STABLE [86ef376bb] 2017-02-09 15:49:58 -0500 +--> + <para> + Fix roundoff problems in <function>float8_timestamptz()</> + and <function>make_interval()</> (Tom Lane) + </para> + + <para> + These functions truncated, rather than rounded, when converting a + floating-point value to integer microseconds; that could cause + unexpectedly off-by-one results. + </para> + </listitem> + + <listitem> +<!-- +Author: Alvaro Herrera <[email protected]> +Branch: master [a3eac988c] 2017-03-16 12:51:08 -0300 +Branch: REL9_6_STABLE [41306a511] 2017-03-16 12:51:08 -0300 +Branch: REL9_5_STABLE [087e696f0] 2017-03-16 12:51:08 -0300 +Branch: REL9_6_STABLE [1ec36a9eb] 2017-04-16 20:49:40 -0400 +Branch: REL9_5_STABLE [b6e6ae1dc] 2017-04-16 20:50:31 -0400 +--> + <para> + Fix <function>pg_get_object_address()</> to handle members of operator + families correctly (Álvaro Herrera) + </para> + </listitem> + + <listitem> +<!-- +Author: Teodor Sigaev <[email protected]> +Branch: master [78874531b] 2017-03-24 13:53:40 +0300 +Branch: REL9_6_STABLE [8de6278d3] 2017-03-24 13:55:02 +0300 +--> + <para> + Fix cancelling of <function>pg_stop_backup()</> when attempting to stop + a non-exclusive backup (Michael Paquier, David Steele) + </para> + + <para> + If <function>pg_stop_backup()</> was cancelled while waiting for a + non-exclusive backup to end, related state was left inconsistent; + a new exclusive backup could not be started, and there were other minor + problems. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [af2c5aa88] 2017-05-02 21:50:35 -0400 +Branch: REL9_6_STABLE [c521d5a8d] 2017-05-02 21:50:42 -0400 +Branch: REL9_5_STABLE [724cd4f06] 2017-05-02 21:50:47 -0400 +Branch: REL9_4_STABLE [5557b6af5] 2017-05-02 21:50:52 -0400 +Branch: REL9_3_STABLE [35ac926bf] 2017-05-02 21:50:56 -0400 +Branch: REL9_2_STABLE [1b6db75ef] 2017-05-02 21:51:01 -0400 +Branch: master [5788a5670] 2017-05-07 11:34:31 -0400 +Branch: REL9_6_STABLE [5042e9492] 2017-05-07 11:34:41 -0400 +Branch: REL9_5_STABLE [38ed45c91] 2017-05-07 11:34:48 -0400 +Branch: REL9_4_STABLE [6eedc6c18] 2017-05-07 11:34:58 -0400 +Branch: REL9_3_STABLE [07987304d] 2017-05-07 11:35:05 -0400 +Branch: REL9_2_STABLE [9061680f0] 2017-05-07 11:35:11 -0400 +--> + <para> + Improve performance of <structname>pg_timezone_names</> view + (Tom Lane, David Rowley) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [ff97741bc] 2017-03-08 12:21:23 -0500 +Branch: REL9_6_STABLE [e0a6ed8a2] 2017-03-08 12:21:12 -0500 +Branch: REL9_5_STABLE [50a9d714a] 2017-03-08 12:21:12 -0500 +Branch: REL9_4_STABLE [8dd5c4171] 2017-03-08 12:21:12 -0500 +--> + <para> + Reduce memory management overhead for contexts containing many large + blocks (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [f97de05a1] 2017-02-21 17:51:37 -0500 +Branch: REL9_6_STABLE [62ed08422] 2017-02-21 17:51:27 -0500 +Branch: REL9_5_STABLE [ff1b032a9] 2017-02-21 17:51:28 -0500 +Branch: REL9_4_STABLE [d9959e6eb] 2017-02-21 17:51:28 -0500 +Branch: REL9_3_STABLE [3f613c6a4] 2017-02-21 17:51:28 -0500 +Branch: REL9_2_STABLE [775227590] 2017-02-21 17:51:28 -0500 +--> + <para> + Fix sloppy handling of corner-case errors from <function>lseek()</> + and <function>close()</> (Tom Lane) + </para> + + <para> + Neither of these system calls are likely to fail in typical situations, + but if they did, <filename>fd.c</> could get quite confused. + </para> + </listitem> + + <listitem> +<!-- +Author: Heikki Linnakangas <[email protected]> +Branch: master [ff30aec75] 2017-03-17 11:14:01 +0200 +Branch: REL9_6_STABLE [38bdba54a] 2017-03-17 11:14:36 +0200 +Branch: REL9_5_STABLE [96fd76dd2] 2017-03-17 11:14:45 +0200 +Branch: REL9_4_STABLE [6b584c36a] 2017-03-17 11:14:49 +0200 +Branch: REL9_3_STABLE [3ebcc2498] 2017-03-17 11:14:53 +0200 +Branch: REL9_2_STABLE [9c52ddfce] 2017-03-17 11:14:58 +0200 +Branch: REL9_6_STABLE [4ae0805bb] 2017-03-24 12:39:23 +0200 +Branch: REL9_5_STABLE [42a60aa7f] 2017-03-24 12:39:20 +0200 +Branch: REL9_4_STABLE [6423ed7d4] 2017-03-24 12:39:17 +0200 +Branch: REL9_3_STABLE [e0e1ef46d] 2017-03-24 12:39:14 +0200 +Branch: REL9_2_STABLE [8ae3ff64b] 2017-03-24 12:39:01 +0200 +--> + <para> + Fix incorrect check for whether postmaster is running as a Windows + service (Michael Paquier) + </para> + + <para> + This could result in attempting to write to the event log when that + isn't accessible, so that no logging happens at all. + </para> + </listitem> + + <listitem> +<!-- +Author: Michael Meskes <[email protected]> +Branch: master [43c79c7d6] 2017-03-13 21:03:55 +0100 +Branch: REL9_6_STABLE [f08a90ecd] 2017-03-13 20:50:48 +0100 +Branch: REL9_5_STABLE [a8b3262ab] 2017-03-13 20:51:46 +0100 +Branch: REL9_4_STABLE [e060baaad] 2017-03-13 20:51:56 +0100 +Branch: REL9_3_STABLE [04207ef76] 2017-03-13 20:52:05 +0100 +Branch: REL9_2_STABLE [d8c207437] 2017-03-13 20:52:16 +0100 +--> + <para> + Fix <application>ecpg</> to support <command>COMMIT PREPARED</> + and <command>ROLLBACK PREPARED</> (Masahiko Sawada) + </para> + </listitem> + + <listitem> +<!-- +Author: Michael Meskes <[email protected]> +Branch: master [d1ca82d0a] 2017-03-10 10:32:41 +0100 +Branch: REL9_6_STABLE [d0fef0654] 2017-03-10 10:50:46 +0100 +Branch: REL9_5_STABLE [466ee7a53] 2017-03-10 10:51:24 +0100 +Branch: REL9_4_STABLE [f6b906599] 2017-03-10 10:51:40 +0100 +Branch: REL9_3_STABLE [af471919b] 2017-03-10 10:51:51 +0100 +Branch: REL9_2_STABLE [731afc91f] 2017-03-10 10:52:01 +0100 +--> + <para> + Fix a double-free error when processing dollar-quoted string literals + in <application>ecpg</> (Michael Meskes) + </para> + </listitem> + + <listitem> +<!-- +Author: Teodor Sigaev <[email protected]> +Branch: REL9_6_STABLE [2ed391f95] 2017-03-24 19:23:13 +0300 +--> + <para> + Fix <application>pgbench</> to handle the combination + of <option>--connect</> and <option>--rate</> options correctly + (Fabien Coelho) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [ef2662394] 2017-03-07 11:36:42 -0500 +Branch: REL9_6_STABLE [0e2c85d13] 2017-03-07 11:36:35 -0500 +--> + <para> + Fix <application>pgbench</> to honor the long-form option + spelling <option>--builtin</>, as per its documentation (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Stephen Frost <[email protected]> +Branch: master [330b84d8c] 2017-03-06 23:29:02 -0500 +Branch: REL9_6_STABLE [e961341cc] 2017-03-06 23:29:08 -0500 +--> + <para> + Fix <application>pg_dump</>/<application>pg_restore</> to correctly + handle privileges for the <literal>public</> schema when + using <option>--clean</> option (Stephen Frost) + </para> + + <para> + Other schemas start out with no privileges granted, + but <literal>public</> does not; this requires special-case treatment + when it is dropped and restored due to the <option>--clean</> option. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [299990ba1] 2017-03-06 19:33:59 -0500 +Branch: REL9_6_STABLE [8ea8178cd] 2017-03-06 19:33:59 -0500 +Branch: REL9_5_STABLE [b6882e9ec] 2017-03-06 19:33:59 -0500 +Branch: REL9_4_STABLE [db9b4b716] 2017-03-06 19:33:59 -0500 +Branch: REL9_3_STABLE [783acfd4d] 2017-03-06 19:33:59 -0500 +Branch: REL9_2_STABLE [0ab75448e] 2017-03-06 19:33:59 -0500 +--> + <para> + In <application>pg_dump</>, fix incorrect schema and owner marking for + comments and security labels of some types of database objects + (Giuseppe Broccolo, Tom Lane) + </para> + + <para> + In simple cases this caused no ill effects; but for example, a + schema-selective restore might omit comments it should include, because + they were not marked as belonging to the schema of their associated + object. + </para> + </listitem> + + <listitem> +<!-- +Author: Peter Eisentraut <[email protected]> +Branch: master [39370e6a0] 2017-02-17 15:06:28 -0500 +Branch: REL9_6_STABLE [4e8b2fd33] 2017-02-17 15:06:34 -0500 +--> + <para> + Fix typo in <application>pg_dump</>'s query for initial privileges + of a procedural language (Peter Eisentraut) + </para> + + <para> + This resulted in <application>pg_dump</> always believing that the + language had no initial privileges. Since that's true for most + procedural languages, ill effects from this bug are probably rare. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [f39ddd843] 2017-03-10 14:15:09 -0500 +Branch: REL9_6_STABLE [4cdd81d90] 2017-03-10 14:15:09 -0500 +Branch: REL9_5_STABLE [88f3743cb] 2017-03-10 14:15:09 -0500 +Branch: REL9_4_STABLE [64d132c29] 2017-03-10 14:15:09 -0500 +Branch: REL9_3_STABLE [0c0a95c2f] 2017-03-10 14:15:09 -0500 +Branch: REL9_2_STABLE [e6d2ba419] 2017-03-10 14:15:09 -0500 +--> + <para> + Avoid emitting an invalid list file in <literal>pg_restore -l</> + when SQL object names contain newlines (Tom Lane) + </para> + + <para> + Replace newlines by spaces, which is sufficient to make the output + valid for <literal>pg_restore -L</>'s purposes. + </para> + </listitem> + + <listitem> +<!-- +Author: Stephen Frost <[email protected]> +Branch: master [ff992c074] 2017-03-06 17:03:57 -0500 +Branch: REL9_6_STABLE [65a3f233b] 2017-03-06 17:04:06 -0500 +Branch: REL9_5_STABLE [6be8647f7] 2017-03-06 17:04:13 -0500 +Branch: REL9_4_STABLE [93598898c] 2017-03-06 17:04:22 -0500 +Branch: REL9_3_STABLE [7f831f09b] 2017-03-06 17:04:29 -0500 +Branch: REL9_2_STABLE [e864cd25b] 2017-03-06 17:04:55 -0500 +--> + <para> + Fix <application>pg_upgrade</> to transfer comments and security labels + attached to <quote>large objects</> (blobs) (Stephen Frost) + </para> + + <para> + Previously, blobs were correctly transferred to the new database, but + any comments or security labels attached to them were lost. + </para> + </listitem> + + <listitem> +<!-- +Author: Noah Misch <[email protected]> +Branch: master [944a026b4] 2017-03-12 19:35:31 -0400 +Branch: REL9_6_STABLE [08c6d42c8] 2017-03-12 19:35:49 -0400 +Branch: REL9_5_STABLE [d0e5ac736] 2017-03-12 19:35:57 -0400 +Branch: REL9_4_STABLE [4b2669ada] 2017-03-12 19:36:06 -0400 +Branch: REL9_3_STABLE [e03c6d93b] 2017-03-12 19:36:15 -0400 +Branch: REL9_2_STABLE [0276da5eb] 2017-03-12 19:36:28 -0400 +--> + <para> + Improve error handling + in <filename>contrib/adminpack</>'s <function>pg_file_write()</> + function (Noah Misch) + </para> + + <para> + Notably, it failed to detect errors reported + by <function>fclose()</>. + </para> + </listitem> + + <listitem> +<!-- +Author: Joe Conway <[email protected]> +Branch: master [cd1e23e93] 2017-03-11 13:32:18 -0800 +Branch: REL9_6_STABLE [8469923f3] 2017-03-11 13:32:26 -0800 +Branch: REL9_5_STABLE [82f3792a4] 2017-03-11 13:32:40 -0800 +Branch: REL9_4_STABLE [166dfb3a9] 2017-03-11 13:33:14 -0800 +Branch: REL9_3_STABLE [f6cfc14e5] 2017-03-11 13:33:22 -0800 +Branch: REL9_2_STABLE [c4613c3f4] 2017-03-11 13:33:30 -0800 +--> + <para> + In <filename>contrib/dblink</>, avoid leaking the previous unnamed + connection when establishing a new unnamed connection (Joe Conway) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [9e43e8714] 2017-02-22 15:04:26 -0500 +Branch: REL9_6_STABLE [16500d227] 2017-02-22 15:04:07 -0500 +Branch: REL9_5_STABLE [513c9f9de] 2017-02-22 15:04:07 -0500 +Branch: REL9_4_STABLE [98755681a] 2017-02-22 15:04:07 -0500 +Branch: REL9_3_STABLE [53b5a8c13] 2017-02-22 15:04:07 -0500 +Branch: master [1dffabed4] 2017-04-14 14:52:21 -0400 +Branch: REL9_6_STABLE [d51279433] 2017-04-14 14:52:03 -0400 +Branch: REL9_5_STABLE [9b48ce377] 2017-04-14 14:52:03 -0400 +Branch: REL9_4_STABLE [e0eda580d] 2017-04-14 14:52:03 -0400 +Branch: REL9_3_STABLE [fad06b287] 2017-04-14 14:52:03 -0400 +Branch: master [6cfaffc0d] 2017-04-13 17:18:35 -0400 +Branch: REL9_6_STABLE [a70b18b89] 2017-04-13 17:18:35 -0400 +Branch: REL9_5_STABLE [67665a71c] 2017-04-13 17:18:35 -0400 +Branch: REL9_4_STABLE [b179684c7] 2017-04-13 17:18:35 -0400 +Branch: REL9_3_STABLE [5be58cc89] 2017-04-13 17:18:35 -0400 +--> + <para> + Fix <filename>contrib/pg_trgm</>'s extraction of trigrams from regular + expressions (Tom Lane) + </para> + + <para> + In some cases it would produce a broken data structure that could never + match anything, leading to GIN or GiST indexscans that use a trigram + index not finding any matches to the regular expression. + </para> + </listitem> + + <listitem> +<!-- +Author: Peter Eisentraut <[email protected]> +Branch: master [332bec1e6] 2017-04-24 22:50:07 -0400 +Branch: REL9_6_STABLE [86e640a69] 2017-04-26 09:14:21 -0400 +--> + <para> + In <filename>contrib/postgres_fdw</>, allow join conditions that + contain shippable extension-provided functions to be pushed to the + remote server (David Rowley, Ashutosh Bapat) + </para> + </listitem> + + <listitem> +<!-- +Author: Alvaro Herrera <[email protected]> +Branch: master [14722c69f] 2017-05-05 12:38:29 -0300 +Branch: REL9_6_STABLE [19a403378] 2017-05-05 12:05:34 -0300 +Branch: REL9_5_STABLE [adfad4222] 2017-05-05 12:05:34 -0300 +Branch: REL9_4_STABLE [41ba2ca08] 2017-05-05 12:05:34 -0300 +Branch: REL9_3_STABLE [f692583dd] 2017-05-05 12:05:34 -0300 +Branch: REL9_2_STABLE [992e581bf] 2017-05-05 12:05:34 -0300 +--> + <para> + Support Tcl 8.6 in MSVC builds (Álvaro Herrera) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [e18b2c480] 2017-04-30 15:13:51 -0400 +Branch: REL9_6_STABLE [6872d96a3] 2017-04-30 15:14:06 -0400 +Branch: REL9_5_STABLE [4d4d8fa77] 2017-04-30 15:14:11 -0400 +Branch: REL9_4_STABLE [96cad6f24] 2017-04-30 15:14:15 -0400 +Branch: REL9_3_STABLE [f8cf9719d] 2017-04-30 15:14:20 -0400 +Branch: REL9_2_STABLE [54aeb8d3e] 2017-04-30 15:14:24 -0400 +Branch: master [a54d5875f] 2017-05-07 12:33:12 -0400 +Branch: REL9_6_STABLE [fab2d0d7f] 2017-05-07 12:33:18 -0400 +Branch: REL9_5_STABLE [74e747fbd] 2017-05-07 12:33:22 -0400 +Branch: REL9_4_STABLE [e829385f5] 2017-05-07 12:33:27 -0400 +Branch: REL9_3_STABLE [9e5f3d013] 2017-05-07 12:33:31 -0400 +Branch: REL9_2_STABLE [da55df018] 2017-05-07 12:33:35 -0400 +--> + <para> + Sync our copy of the timezone library with IANA release tzcode2017b + (Tom Lane) + </para> + + <para> + This fixes a bug affecting some DST transitions in January 2038. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [74a20d0ab] 2017-05-01 11:53:11 -0400 +Branch: REL9_6_STABLE [1fdc3f6e8] 2017-05-01 11:53:42 -0400 +Branch: REL9_5_STABLE [9a8cc157c] 2017-05-01 11:53:49 -0400 +Branch: REL9_4_STABLE [1c8862346] 2017-05-01 11:53:56 -0400 +Branch: REL9_3_STABLE [dc93cafca] 2017-05-01 11:54:02 -0400 +Branch: REL9_2_STABLE [c96ccc40e] 2017-05-01 11:54:08 -0400 +--> + <para> + Update time zone data files to <application>tzdata</> release 2017b + for DST law changes in Chile, Haiti, and Mongolia, plus historical + corrections for Ecuador, Kazakhstan, Liberia, and Spain. + Switch to numeric abbreviations for numerous time zones in South + America, the Pacific and Indian oceans, and some Asian and Middle + Eastern countries. + </para> + + <para> + The IANA time zone database previously provided textual abbreviations + for all time zones, sometimes making up abbreviations that have little + or no currency among the local population. They are in process of + reversing that policy in favor of using numeric UTC offsets in zones + where there is no evidence of real-world use of an English + abbreviation. At least for the time being, <productname>PostgreSQL</> + will continue to accept such removed abbreviations for timestamp input. + But they will not be shown in the <structname>pg_timezone_names</> + view nor used for output. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [d4e59c552] 2017-05-07 11:57:41 -0400 +Branch: REL9_6_STABLE [f75472817] 2017-05-07 11:57:41 -0400 +Branch: REL9_5_STABLE [2f66002df] 2017-05-07 11:57:41 -0400 +Branch: REL9_4_STABLE [62a288312] 2017-05-07 11:57:41 -0400 +Branch: REL9_3_STABLE [5971accd8] 2017-05-07 11:57:41 -0400 +Branch: REL9_2_STABLE [82e7d3dfd] 2017-05-07 11:57:41 -0400 +--> + <para> + Use correct daylight-savings rules for POSIX-style time zone names + in MSVC builds (David Rowley) + </para> + + <para> + The Microsoft MSVC build scripts neglected to install + the <filename>posixrules</> file in the timezone directory tree. + This resulted in the timezone code falling back to its built-in + rule about what DST behavior to assume for a POSIX-style time zone + name. For historical reasons that still corresponds to the DST rules + the USA was using before 2007 (i.e., change on first Sunday in April + and last Sunday in October). With this fix, a POSIX-style zone name + will use the current and historical DST transition dates of + the <literal>US/Eastern</> zone. If you don't want that, remove + the <filename>posixrules</> file, or replace it with a copy of some + other zone file (see <xref linkend="datatype-timezones">). Note that + due to caching, you may need to restart the server to get such changes + to take effect. + </para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + + <sect1 id="release-9-6-2"> + <title>Release 9.6.2</title> + + <formalpara> + <title>Release date:</title> + <para>2017-02-09</para> + </formalpara> + + <para> + This release contains a variety of fixes from 9.6.1. + For information about new features in the 9.6 major release, see + <xref linkend="release-9-6">. + </para> + + <sect2> + <title>Migration to Version 9.6.2</title> + + <para> + A dump/restore is not required for those running 9.6.X. + </para> + + <para> + However, if your installation has been affected by the bug described in + the first changelog entry below, then after updating you may need + to take action to repair corrupted indexes. + </para> + + <para> + Also, if you are upgrading from a version earlier than 9.6.1, + see <xref linkend="release-9-6-1">. + </para> + </sect2> + + <sect2> + <title>Changes</title> + + <itemizedlist> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [2aaec6546] 2017-02-06 13:20:19 -0500 +Branch: REL9_6_STABLE [7fcddbdd0] 2017-02-06 13:20:20 -0500 +Branch: REL9_5_STABLE [e935696f4] 2017-02-06 13:20:21 -0500 +Branch: REL9_4_STABLE [5879958e1] 2017-02-06 13:20:23 -0500 +Branch: REL9_3_STABLE [32c893c8d] 2017-02-06 13:20:24 -0500 +Branch: REL9_2_STABLE [bcd7b47c2] 2017-02-06 13:20:25 -0500 +--> + <para> + Fix a race condition that could cause indexes built + with <command>CREATE INDEX CONCURRENTLY</> to be corrupt + (Pavan Deolasee, Tom Lane) + </para> + + <para> + If <command>CREATE INDEX CONCURRENTLY</> was used to build an index + that depends on a column not previously indexed, then rows + updated by transactions that ran concurrently with + the <command>CREATE INDEX</> command could have received incorrect + index entries. If you suspect this may have happened, the most + reliable solution is to rebuild affected indexes after installing + this update. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [ffaa44cb5] 2016-11-15 15:55:35 -0500 +Branch: REL9_6_STABLE [8aa3e4751] 2016-11-15 15:55:35 -0500 +Branch: REL9_5_STABLE [0bc3ed98c] 2016-11-15 15:55:35 -0500 +Branch: REL9_4_STABLE [3e844a34b] 2016-11-15 15:55:36 -0500 +--> + <para> + Ensure that the special snapshot used for catalog scans is not + invalidated by premature data pruning (Tom Lane) + </para> + + <para> + Backends failed to account for this snapshot when advertising their + oldest xmin, potentially allowing concurrent vacuuming operations to + remove data that was still needed. This led to transient failures + along the lines of <quote>cache lookup failed for relation 1255</>. + </para> + </listitem> + + <listitem> +<!-- +Author: Alvaro Herrera <[email protected]> +Branch: master [7403561c0] 2017-01-09 18:19:29 -0300 +Branch: REL9_6_STABLE [4482c6a23] 2017-01-09 18:19:29 -0300 +Branch: REL9_5_STABLE [ed8e8b814] 2017-01-09 18:19:29 -0300 +--> + <para> + Fix incorrect WAL logging for BRIN indexes (Kuntal Ghosh) + </para> + + <para> + The WAL record emitted for a BRIN <quote>revmap</> page when moving an + index tuple to a different page was incorrect. Replay would make the + related portion of the index useless, forcing it to be recomputed. + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [fa0f466d5] 2016-12-08 14:12:08 -0500 +Branch: REL9_6_STABLE [1ed3c6ff9] 2016-12-08 14:13:55 -0500 +Branch: REL9_5_STABLE [141ad6896] 2016-12-08 14:14:12 -0500 +Branch: REL9_4_STABLE [68e56eef6] 2016-12-08 14:14:27 -0500 +Branch: REL9_3_STABLE [8e403f215] 2016-12-08 14:16:47 -0500 +Branch: REL9_2_STABLE [a00ac6299] 2016-12-08 14:19:25 -0500 +--> + <para> + Unconditionally WAL-log creation of the <quote>init fork</> for an + unlogged table (Michael Paquier) + </para> + + <para> + Previously, this was skipped when <xref linkend="guc-wal-level"> + = <literal>minimal</>, but actually it's necessary even in that case + to ensure that the unlogged table is properly reset to empty after a + crash. + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [4f714b2fd] 2016-10-27 14:27:40 -0400 +Branch: REL9_6_STABLE [4a43a6244] 2016-10-27 14:54:35 -0400 +Branch: REL9_5_STABLE [0cbd199fd] 2016-10-27 14:54:39 -0400 +Branch: REL9_4_STABLE [4a8cfbdcb] 2016-10-27 14:56:37 -0400 +Branch: REL9_3_STABLE [e927f55ff] 2016-10-27 14:56:42 -0400 +Branch: REL9_2_STABLE [2be2838a7] 2016-10-27 14:56:53 -0400 +--> + <para> + If the stats collector dies during hot standby, restart it (Takayuki + Tsunakawa) + </para> + </listitem> + + <listitem> +<!-- +Author: Simon Riggs <[email protected]> +Branch: master [ec4b97501] 2017-01-26 18:14:02 +0000 +Branch: REL9_6_STABLE [95d1b4145] 2017-01-26 20:06:44 +0000 +Branch: REL9_5_STABLE [99289e506] 2017-01-26 20:09:18 +0000 +Branch: REL9_4_STABLE [800d89a98] 2017-01-26 20:10:19 +0000 +Branch: REL9_3_STABLE [048d44175] 2017-01-26 20:15:23 +0000 +--> + <para> + Ensure that hot standby feedback works correctly when it's enabled at + standby server start (Ants Aasma, Craig Ringer) + </para> + </listitem> + + <listitem> +<!-- +Author: Simon Riggs <[email protected]> +Branch: master [e8ee3d6b8] 2017-01-26 18:59:58 +0000 +Branch: REL9_6_STABLE [40b7800da] 2017-01-27 12:13:20 +0000 +Branch: REL9_5_STABLE [ace2cd80a] 2017-01-27 12:15:02 +0000 +Branch: REL9_4_STABLE [357e06128] 2017-01-27 12:16:18 +0000 +Branch: REL9_3_STABLE [332068a21] 2017-01-27 12:18:07 +0000 +Branch: REL9_2_STABLE [15c54e836] 2017-01-27 12:19:50 +0000 +--> + <para> + Check for interrupts while hot standby is waiting for a conflicting + query (Simon Riggs) + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [c6a389792] 2017-01-20 15:55:45 -0500 +Branch: REL9_6_STABLE [746ba76f1] 2017-01-20 16:11:45 -0500 +Branch: REL9_5_STABLE [aeaaf62aa] 2017-01-20 16:14:11 -0500 +Branch: REL9_4_STABLE [806f9b3d7] 2017-01-20 16:16:46 -0500 +Branch: REL9_3_STABLE [5c5788e90] 2017-01-20 16:18:55 -0500 +Branch: REL9_2_STABLE [5dff230eb] 2017-01-20 16:26:39 -0500 +--> + <para> + Avoid constantly respawning the autovacuum launcher in a corner case + (Amit Khandekar) + </para> + + <para> + This fix avoids problems when autovacuum is nominally off and there + are some tables that require freezing, but all such tables are + already being processed by autovacuum workers. + </para> + </listitem> + + <listitem> +<!-- +Author: Fujii Masao <[email protected]> +Branch: master [93eb619cd] 2016-12-17 02:22:15 +0900 +Branch: REL9_6_STABLE [6c75fb6b3] 2016-12-17 02:25:47 +0900 +--> + <para> + Disallow setting the <replaceable>num_sync</> field to zero in + <xref linkend="guc-synchronous-standby-names"> (Fujii Masao) + </para> + + <para> + The correct way to disable synchronous standby is to set the whole + value to an empty string. + </para> + </listitem> + + <listitem> +<!-- +Author: Andrew Dunstan <[email protected]> +Branch: master [f1169ab50] 2017-02-01 18:02:43 -0500 +Branch: REL9_6_STABLE [13752743b] 2017-02-01 17:59:53 -0500 +--> + <para> + Don't count background worker processes against a user's connection + limit (David Rowley) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [182db0704] 2016-11-26 13:31:35 -0500 +Branch: REL9_6_STABLE [0cc8453ac] 2016-11-26 13:31:35 -0500 +Branch: REL9_5_STABLE [576bd360b] 2016-11-26 13:31:35 -0500 +Branch: REL9_4_STABLE [313786a74] 2016-11-26 13:31:35 -0500 +Branch: REL9_3_STABLE [2cbb62db1] 2016-11-26 13:31:35 -0500 +Branch: REL9_2_STABLE [a982b02a4] 2016-11-26 13:31:35 -0500 +--> + <para> + Fix check for when an extension member object can be dropped (Tom Lane) + </para> + + <para> + Extension upgrade scripts should be able to drop member objects, + but this was disallowed for serial-column sequences, and possibly + other cases. + </para> + </listitem> + + <listitem> +<!-- +Author: Stephen Frost <[email protected]> +Branch: master [e54f75722] 2017-01-29 23:05:07 -0500 +Branch: REL9_6_STABLE [20064c0ec] 2017-01-29 23:05:09 -0500 +--> + <para> + Fix tracking of initial privileges for extension member objects so + that it works correctly with <command>ALTER EXTENSION ... ADD/DROP</> + (Stephen Frost) + </para> + + <para> + An object's current privileges at the time it is added to the + extension will now be considered its default privileges; only + later changes in its privileges will be dumped by + subsequent <application>pg_dump</> runs. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [bd673e8e8] 2016-11-23 13:45:55 -0500 +Branch: REL9_6_STABLE [4a5e1d370] 2016-11-23 13:45:56 -0500 +Branch: REL9_5_STABLE [e0375d77b] 2016-11-23 13:45:56 -0500 +Branch: REL9_4_STABLE [15f3e0cb1] 2016-11-23 13:45:56 -0500 +Branch: REL9_3_STABLE [8f67a6c22] 2016-11-23 13:45:56 -0500 +Branch: REL9_2_STABLE [05975ab0a] 2016-11-23 13:45:56 -0500 +--> + <para> + Make sure <command>ALTER TABLE</> preserves index tablespace + assignments when rebuilding indexes (Tom Lane, Michael Paquier) + </para> + + <para> + Previously, non-default settings + of <xref linkend="guc-default-tablespace"> could result in broken + indexes. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [a522fc3d8] 2016-10-26 17:05:06 -0400 +Branch: REL9_6_STABLE [445035a6e] 2016-10-26 17:05:06 -0400 +Branch: REL9_5_STABLE [b53c841e5] 2016-10-26 17:05:06 -0400 +Branch: REL9_4_STABLE [3a9a8c408] 2016-10-26 17:05:06 -0400 +--> + <para> + Fix incorrect updating of trigger function properties when changing a + foreign-key constraint's deferrability properties with <command>ALTER + TABLE ... ALTER CONSTRAINT</> (Tom Lane) + </para> + + <para> + This led to odd failures during subsequent exercise of the foreign + key, as the triggers were fired at the wrong times. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [4e026b32d] 2016-11-25 13:44:47 -0500 +Branch: REL9_6_STABLE [bf5fe7bfa] 2016-11-25 13:44:47 -0500 +Branch: REL9_5_STABLE [6cbe84c82] 2016-11-25 13:44:48 -0500 +Branch: REL9_4_STABLE [f7166ce24] 2016-11-25 13:44:48 -0500 +Branch: REL9_3_STABLE [05bef7b08] 2016-11-25 13:44:48 -0500 +Branch: REL9_2_STABLE [6a363a4c2] 2016-11-25 13:44:48 -0500 +--> + <para> + Prevent dropping a foreign-key constraint if there are pending + trigger events for the referenced relation (Tom Lane) + </para> + + <para> + This avoids <quote>could not find trigger <replaceable>NNN</></quote> + or <quote>relation <replaceable>NNN</> has no triggers</quote> errors. + </para> + </listitem> + + <listitem> +<!-- +Author: Alvaro Herrera <[email protected]> +Branch: master [3957b58b8] 2017-01-09 19:26:58 -0300 +Branch: REL9_6_STABLE [4e563a1f6] 2017-01-09 19:26:58 -0300 +Branch: REL9_5_STABLE [4d4ab6ccd] 2017-01-09 19:26:58 -0300 +--> + <para> + Fix <command>ALTER TABLE ... SET DATA TYPE ... USING</> when child + table has different column ordering than the parent + (Álvaro Herrera) + </para> + + <para> + Failure to adjust the column numbering in the <literal>USING</> + expression led to errors, + typically <quote>attribute <replaceable>N</> has wrong type</quote>. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [d86f40009] 2017-01-04 18:00:11 -0500 +Branch: REL9_6_STABLE [f64554b99] 2017-01-04 18:00:11 -0500 +Branch: REL9_5_STABLE [50c8196f9] 2017-01-04 18:00:11 -0500 +Branch: REL9_4_STABLE [696d40d30] 2017-01-04 18:00:11 -0500 +Branch: REL9_3_STABLE [5f89a9885] 2017-01-04 18:00:12 -0500 +Branch: REL9_2_STABLE [6c4cf2be8] 2017-01-04 18:00:12 -0500 +--> + <para> + Fix processing of OID column when a table with OIDs is associated to + a parent with OIDs via <command>ALTER TABLE ... INHERIT</> (Amit + Langote) + </para> + + <para> + The OID column should be treated the same as regular user columns in + this case, but it wasn't, leading to odd behavior in later + inheritance changes. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [1ead0208b] 2016-12-22 16:23:38 -0500 +Branch: REL9_6_STABLE [68330c8b4] 2016-12-22 16:23:34 -0500 +--> + <para> + Ensure that <command>CREATE TABLE ... LIKE ... WITH OIDS</> creates + a table with OIDs, whether or not the <literal>LIKE</>-referenced + table(s) have OIDs (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Dean Rasheed <[email protected]> +Branch: master [58b136264] 2016-12-21 16:58:18 +0000 +Branch: REL9_6_STABLE [a46ee6b30] 2016-12-21 17:01:52 +0000 +Branch: REL9_5_STABLE [78a98b767] 2016-12-21 17:02:47 +0000 +Branch: REL9_4_STABLE [cad24980e] 2016-12-21 17:03:54 +0000 +--> + <para> + Fix <command>CREATE OR REPLACE VIEW</> to update the view query + before attempting to apply the new view options (Dean Rasheed) + </para> + + <para> + Previously the command would fail if the new options were + inconsistent with the old view definition. + </para> + </listitem> + + <listitem> +<!-- +Author: Stephen Frost <[email protected]> +Branch: master [12bd7dd31] 2016-12-22 17:08:43 -0500 +Branch: REL9_6_STABLE [f0f2e56ac] 2016-12-22 17:08:47 -0500 +Branch: REL9_5_STABLE [e82369217] 2016-12-22 17:08:49 -0500 +Branch: REL9_4_STABLE [ac1ec9c1f] 2016-12-22 17:08:58 -0500 +Branch: REL9_3_STABLE [0e3aadb68] 2016-12-22 17:09:00 -0500 +--> + <para> + Report correct object identity during <command>ALTER TEXT SEARCH + CONFIGURATION</> (Artur Zakirov) + </para> + + <para> + The wrong catalog OID was reported to extensions such as logical + decoding. + </para> + </listitem> + + <listitem> +<!-- +Author: Alvaro Herrera <[email protected]> +Branch: master [4aaddf2f0] 2016-11-24 15:39:55 -0300 +Branch: REL9_6_STABLE [9b6634290] 2016-11-24 15:39:55 -0300 +Branch: REL9_5_STABLE [7816d1356] 2016-11-24 15:39:55 -0300 +--> + <para> + Fix commit timestamp mechanism to not fail when queried about + the special XIDs <literal>FrozenTransactionId</> + and <literal>BootstrapTransactionId</> (Craig Ringer) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [e3e66d8a9] 2016-11-07 12:08:18 -0500 +Branch: REL9_6_STABLE [5ee3a7453] 2016-11-07 12:08:19 -0500 +Branch: REL9_5_STABLE [e2f5cd9cf] 2016-11-07 12:08:19 -0500 +Branch: master [530f80652] 2016-11-10 15:00:58 -0500 +Branch: REL9_6_STABLE [05a6e8728] 2016-11-10 15:00:58 -0500 +Branch: REL9_5_STABLE [6e00ba1e1] 2016-11-10 15:00:58 -0500 +--> + <para> + Fix incorrect use of view reloptions as regular table reloptions (Tom + Lane) + </para> + + <para> + The symptom was spurious <quote>ON CONFLICT is not supported on table + ... used as a catalog table</> errors when the target + of <command>INSERT ... ON CONFLICT</> is a view with cascade option. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [385072320] 2016-12-04 15:02:45 -0500 +Branch: REL9_6_STABLE [da05d0ebc] 2016-12-04 15:02:46 -0500 +Branch: REL9_5_STABLE [25c06a1ed] 2016-12-04 15:02:48 -0500 +--> + <para> + Fix incorrect <quote>target lists can have at most <replaceable>N</> + entries</quote> complaint when using <literal>ON CONFLICT</> with + wide tables (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [da8f3ebf3] 2016-11-02 14:32:13 -0400 +Branch: REL9_6_STABLE [f4d865f22] 2016-11-02 14:32:13 -0400 +--> + <para> + Fix spurious <quote>query provides a value for a dropped column</> + errors during <command>INSERT</> or <command>UPDATE</> on a table + with a dropped column (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [c5f365f3a] 2016-11-20 14:26:19 -0500 +Branch: REL9_6_STABLE [90f8b4be5] 2016-11-20 14:26:19 -0500 +Branch: REL9_5_STABLE [aeb5e8242] 2016-11-20 14:26:19 -0500 +Branch: REL9_4_STABLE [44c8b4fcd] 2016-11-20 14:26:19 -0500 +Branch: REL9_3_STABLE [71db302ec] 2016-11-20 14:26:19 -0500 +--> + <para> + Prevent multicolumn expansion of <replaceable>foo</><literal>.*</> in + an <command>UPDATE</> source expression (Tom Lane) + </para> + + <para> + This led to <quote>UPDATE target count mismatch --- internal + error</>. Now the syntax is understood as a whole-row variable, + as it would be in other contexts. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [0b78106cd] 2016-12-08 11:40:02 -0500 +Branch: REL9_6_STABLE [cf22c8cb8] 2016-12-09 12:01:14 -0500 +Branch: REL9_5_STABLE [6a493adda] 2016-12-09 12:01:14 -0500 +Branch: REL9_4_STABLE [c7a62135a] 2016-12-09 12:01:14 -0500 +Branch: REL9_3_STABLE [2afe282a3] 2016-12-09 12:01:14 -0500 +Branch: REL9_2_STABLE [082d1fb9e] 2016-12-09 12:01:14 -0500 +--> + <para> + Ensure that column typmods are determined accurately for + multi-row <literal>VALUES</> constructs (Tom Lane) + </para> + + <para> + This fixes problems occurring when the first value in a column has a + determinable typmod (e.g., length for a <type>varchar</> value) but + later values don't share the same limit. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [a8ae12322] 2016-12-21 17:39:32 -0500 +Branch: REL9_6_STABLE [88e1e91da] 2016-12-21 17:39:32 -0500 +Branch: REL9_5_STABLE [d5633af7b] 2016-12-21 17:39:32 -0500 +Branch: REL9_4_STABLE [d0f60e4cc] 2016-12-21 17:39:32 -0500 +Branch: REL9_3_STABLE [a57695d9a] 2016-12-21 17:39:33 -0500 +Branch: REL9_2_STABLE [6e2c21ec5] 2016-12-21 17:39:33 -0500 +--> + <para> + Throw error for an unfinished Unicode surrogate pair at the end of a + Unicode string (Tom Lane) + </para> + + <para> + Normally, a Unicode surrogate leading character must be followed by a + Unicode surrogate trailing character, but the check for this was + missed if the leading character was the last character in a Unicode + string literal (<literal>U&'...'</>) or Unicode identifier + (<literal>U&"..."</>). + </para> + </listitem> + + <listitem> +<!-- +Author: Heikki Linnakangas <[email protected]> +Branch: master [db80acfc9] 2016-12-20 09:20:17 +0200 +Branch: REL9_6_STABLE [ce92fc4e2] 2016-12-20 09:20:30 +0200 +--> + <para> + Fix execution of <literal>DISTINCT</> and ordered aggregates when + multiple such aggregates are able to share the same transition state + (Heikki Linnakangas) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [89fcea1ac] 2016-12-21 15:18:39 -0500 +Branch: REL9_6_STABLE [4e2477b7b] 2016-12-21 15:18:40 -0500 +Branch: master [260443847] 2016-12-19 13:49:50 -0500 +Branch: REL9_6_STABLE [3f07eff10] 2016-12-19 13:49:45 -0500 +--> + <para> + Fix implementation of phrase search operators in <type>tsquery</> + (Tom Lane) + </para> + + <para> + Remove incorrect, and inconsistently-applied, rewrite rules that + tried to transform away AND/OR/NOT operators appearing below a PHRASE + operator; instead upgrade the execution engine to handle such cases + correctly. This fixes assorted strange behavior and possible crashes + for text search queries containing such combinations. Also fix + nested PHRASE operators to work sanely in combinations other than + simple left-deep trees, correct the behavior when removing stopwords + from a phrase search clause, and make sure that index searches behave + consistently with simple sequential-scan application of such queries. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [9d4ca0131] 2017-01-26 12:18:07 -0500 +Branch: REL9_6_STABLE [2dfc12647] 2017-01-26 12:17:47 -0500 +Branch: REL9_5_STABLE [423ad86f4] 2017-01-26 12:17:47 -0500 +Branch: REL9_4_STABLE [2c1976a6c] 2017-01-26 12:17:47 -0500 +Branch: REL9_3_STABLE [2e024f83b] 2017-01-26 12:17:47 -0500 +Branch: REL9_2_STABLE [fe6120f9b] 2017-01-26 12:17:47 -0500 +--> + <para> + Ensure that a purely negative text search query, such + as <literal>!foo</>, matches empty <type>tsvector</>s (Tom Dunstan) + </para> + + <para> + Such matches were found by GIN index searches, but not by sequential + scans or GiST index searches. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [0eaaaf00e] 2016-12-11 13:09:57 -0500 +Branch: REL9_6_STABLE [c8bfe055b] 2016-12-11 13:09:57 -0500 +Branch: REL9_5_STABLE [c6caa5200] 2016-12-11 13:09:57 -0500 +Branch: REL9_4_STABLE [6f5cb982e] 2016-12-11 13:09:57 -0500 +Branch: REL9_3_STABLE [79e1a9efa] 2016-12-11 13:09:57 -0500 +Branch: REL9_2_STABLE [f4ccee408] 2016-12-11 13:09:57 -0500 +--> + <para> + Prevent crash when <function>ts_rewrite()</> replaces a non-top-level + subtree with an empty query (Artur Zakirov) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [5ec81acee] 2016-10-30 17:35:42 -0400 +Branch: REL9_6_STABLE [464326e83] 2016-10-30 17:35:42 -0400 +Branch: REL9_5_STABLE [e0491c19d] 2016-10-30 17:35:42 -0400 +Branch: REL9_4_STABLE [514797a52] 2016-10-30 17:35:43 -0400 +Branch: REL9_3_STABLE [407d513df] 2016-10-30 17:35:43 -0400 +Branch: REL9_2_STABLE [606e16a7f] 2016-10-30 17:35:43 -0400 +--> + <para> + Fix performance problems in <function>ts_rewrite()</> (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [24ebc444c] 2016-10-30 15:24:40 -0400 +Branch: REL9_6_STABLE [2a2b439cc] 2016-10-30 15:24:40 -0400 +Branch: REL9_5_STABLE [de7387604] 2016-10-30 15:24:40 -0400 +Branch: REL9_4_STABLE [f0c2ce45e] 2016-10-30 15:24:40 -0400 +Branch: REL9_3_STABLE [77a22f898] 2016-10-30 15:24:40 -0400 +Branch: REL9_2_STABLE [b0f8a273e] 2016-10-30 15:24:40 -0400 +--> + <para> + Fix <function>ts_rewrite()</>'s handling of nested NOT operators + (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [9a00f03e4] 2016-10-30 12:27:41 -0400 +Branch: REL9_6_STABLE [48a6592da] 2016-10-30 12:27:41 -0400 +Branch: REL9_5_STABLE [7151e72d7] 2016-10-30 12:27:41 -0400 +--> + <para> + Improve speed of user-defined aggregates that + use <function>array_append()</> as transition function (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [82f8107b9] 2017-01-05 11:33:51 -0500 +Branch: REL9_6_STABLE [5b4f8f4c6] 2017-01-05 11:33:51 -0500 +Branch: REL9_5_STABLE [4555a375a] 2017-01-05 11:33:51 -0500 +Branch: REL9_4_STABLE [4e446563b] 2017-01-05 11:33:51 -0500 +Branch: REL9_3_STABLE [ee9cb284a] 2017-01-05 11:33:51 -0500 +Branch: REL9_2_STABLE [e0d59c6ef] 2017-01-05 11:33:51 -0500 +--> + <para> + Fix <function>array_fill()</> to handle empty arrays properly (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Alvaro Herrera <[email protected]> +Branch: master [a73491e5f] 2016-12-09 12:42:17 -0300 +Branch: REL9_6_STABLE [79c89f1f4] 2016-12-09 12:42:17 -0300 +Branch: REL9_5_STABLE [581b09c72] 2016-12-09 12:42:17 -0300 +--> + <para> + Fix possible crash in <function>array_position()</> + or <function>array_positions()</> when processing arrays of records + (Junseok Yang) + </para> + </listitem> + + <listitem> +<!-- +Author: Heikki Linnakangas <[email protected]> +Branch: master [4f5182e18] 2016-12-16 12:53:04 +0200 +Branch: REL9_6_STABLE [0fe5a4cd7] 2016-12-16 12:52:50 +0200 +Branch: REL9_5_STABLE [595333ff4] 2016-12-16 12:53:12 +0200 +Branch: REL9_4_STABLE [779325478] 2016-12-16 12:53:16 +0200 +Branch: REL9_3_STABLE [e71fe8470] 2016-12-16 12:53:22 +0200 +Branch: REL9_2_STABLE [c8f8ed5c2] 2016-12-16 12:53:27 +0200 +--> + <para> + Fix one-byte buffer overrun in <function>quote_literal_cstr()</> + (Heikki Linnakangas) + </para> + + <para> + The overrun occurred only if the input consisted entirely of single + quotes and/or backslashes. + </para> + </listitem> + + <listitem> +<!-- +Author: Fujii Masao <[email protected]> +Branch: master [974ece58b] 2017-01-17 17:27:32 +0900 +Branch: REL9_6_STABLE [60a8b63d2] 2017-01-17 17:29:15 +0900 +Branch: REL9_5_STABLE [dfe348c1b] 2017-01-17 17:30:26 +0900 +Branch: REL9_4_STABLE [9e7f00d86] 2017-01-17 17:31:51 +0900 +Branch: REL9_3_STABLE [f64b11fa0] 2017-01-17 17:32:20 +0900 +Branch: REL9_2_STABLE [c73157ca0] 2017-01-17 17:32:45 +0900 +--> + <para> + Prevent multiple calls of <function>pg_start_backup()</> + and <function>pg_stop_backup()</> from running concurrently (Michael + Paquier) + </para> + + <para> + This avoids an assertion failure, and possibly worse things, if + someone tries to run these functions in parallel. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [c22ecc656] 2017-01-18 15:22:07 -0500 +Branch: REL9_6_STABLE [b21e665f2] 2017-01-18 15:21:52 -0500 +Branch: REL9_5_STABLE [74e67bbad] 2017-01-18 15:21:52 -0500 +--> + <para> + Disable transform that attempted to remove no-op <literal>AT TIME + ZONE</> conversions (Tom Lane) + </para> + + <para> + This resulted in wrong answers when the simplified expression was + used in an index condition. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [f0774abde] 2016-12-27 15:43:54 -0500 +Branch: REL9_6_STABLE [21e24eb9a] 2016-12-27 15:43:54 -0500 +Branch: REL9_5_STABLE [4efe7aa2d] 2016-12-27 15:43:54 -0500 +Branch: REL9_4_STABLE [0b947b692] 2016-12-27 15:43:54 -0500 +Branch: REL9_3_STABLE [583599839] 2016-12-27 15:43:54 -0500 +Branch: REL9_2_STABLE [beae7d5f0] 2016-12-27 15:43:55 -0500 +--> + <para> + Avoid discarding <type>interval</>-to-<type>interval</> casts + that aren't really no-ops (Tom Lane) + </para> + + <para> + In some cases, a cast that should result in zeroing out + low-order <type>interval</> fields was mistakenly deemed to be a + no-op and discarded. An example is that casting from <type>INTERVAL + MONTH</> to <type>INTERVAL YEAR</> failed to clear the months field. + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [53c7cff72] 2016-12-05 15:54:28 -0500 +Branch: REL9_6_STABLE [06fa6670f] 2016-12-05 15:59:02 -0500 +--> + <para> + Fix crash if the number of workers available to a parallel query + decreases during a rescan (Andreas Seltenreich) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [13671b4b2] 2016-11-19 14:26:19 -0500 +Branch: REL9_6_STABLE [272c42660] 2016-11-19 14:26:19 -0500 +Branch: REL9_5_STABLE [b9ee42e70] 2016-11-19 14:26:20 -0500 +--> + <para> + Fix bugs in transmitting GUC parameter values to parallel workers + (Michael Paquier, Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [4212cb732] 2016-12-06 11:11:54 -0500 +Branch: REL9_6_STABLE [ebe5dc9e0] 2016-12-06 11:43:12 -0500 +--> + <para> + Allow statements prepared with <command>PREPARE</> to be given + parallel plans (Amit Kapila, Tobias Bussmann) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [41e2b84ce] 2016-11-29 19:32:35 -0500 +Branch: REL9_6_STABLE [e5b8aa636] 2016-11-29 19:32:35 -0500 +--> + <para> + Fix incorrect generation of parallel plans for semi-joins (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [0c2070cef] 2017-01-13 13:34:10 -0500 +Branch: REL9_6_STABLE [2d443ae1b] 2017-01-13 13:36:09 -0500 +--> + <para> + Fix planner's cardinality estimates for parallel joins (Robert Haas) + </para> + + <para> + Ensure that these estimates reflect the number of rows predicted to + be seen by each worker, rather than the total. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [ab77a5a45] 2016-11-25 16:20:12 -0500 +Branch: REL9_6_STABLE [474de765a] 2016-11-25 16:20:31 -0500 +Branch: master [f24cf960d] 2016-11-21 11:09:24 -0500 +Branch: REL9_6_STABLE [01f08cbbc] 2016-11-21 11:09:33 -0500 +--> + <para> + Fix planner to avoid trying to parallelize plan nodes containing + initplans or subplans (Tom Lane, Amit Kapila) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [c52d37c8b] 2017-01-06 14:12:52 -0500 +Branch: REL9_6_STABLE [4103a2f20] 2017-01-06 14:12:52 -0500 +Branch: REL9_5_STABLE [aaf12e577] 2017-01-06 14:12:52 -0500 +Branch: REL9_4_STABLE [e4380e4cf] 2017-01-06 14:12:52 -0500 +Branch: REL9_3_STABLE [a8191800a] 2017-01-06 14:12:52 -0500 +--> + <para> + Ensure that cached plans are invalidated by changes in foreign-table + options (Amit Langote, Etsuro Fujita, Ashutosh Bapat) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [e1b449bea] 2016-11-10 11:31:56 -0500 +Branch: REL9_6_STABLE [7defc3b97] 2016-11-10 11:31:56 -0500 +--> + <para> + Fix the plan generated for sorted partial aggregation with a constant + <literal>GROUP BY</> clause (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [1f542a2ea] 2016-12-13 13:20:37 -0500 +Branch: REL9_6_STABLE [997a2994e] 2016-12-13 13:20:16 -0500 +--> + <para> + Fix <quote>could not find plan for CTE</> planner error when dealing + with a <literal>UNION ALL</> containing CTE references (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [555494d1b] 2017-02-02 19:11:32 -0500 +Branch: REL9_6_STABLE [b971a98ce] 2017-02-02 19:11:27 -0500 +--> + <para> + Fix mishandling of initplans when forcibly adding a Material node to + a subplan (Tom Lane) + </para> + + <para> + The typical consequence of this mistake was a <quote>plan should not + reference subplan's variable</> error. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [7fa93eec4] 2016-12-17 15:28:54 -0500 +Branch: REL9_6_STABLE [f4f195d15] 2016-12-17 15:28:54 -0500 +Branch: master [770671062] 2016-11-02 15:50:15 -0400 +Branch: REL9_6_STABLE [23c6c437f] 2016-11-02 15:50:21 -0400 +--> + <para> + Fix foreign-key-based join selectivity estimation for semi-joins and + anti-joins, as well as inheritance cases (Tom Lane) + </para> + + <para> + The new code for taking the existence of a foreign key relationship + into account did the wrong thing in these cases, making the estimates + worse not better than the pre-9.6 code. + </para> + </listitem> + + <listitem> +<!-- +Author: Stephen Frost <[email protected]> +Branch: master [bec96c82f] 2017-01-19 12:06:21 -0500 +Branch: REL9_6_STABLE [fd081cabf] 2017-01-19 12:06:27 -0500 +--> + <para> + Fix <application>pg_dump</> to emit the data of a sequence that is + marked as an extension configuration table (Michael Paquier) + </para> + </listitem> + + <listitem> +<!-- +Author: Stephen Frost <[email protected]> +Branch: master [e2090d9d2] 2017-01-31 16:24:11 -0500 +Branch: REL9_6_STABLE [eb5e9d90d] 2017-01-31 16:24:14 -0500 +--> + <para> + Fix mishandling of <command>ALTER DEFAULT PRIVILEGES ... REVOKE</> + in <application>pg_dump</> (Stephen Frost) + </para> + + <para> + <application>pg_dump</> missed issuing the + required <literal>REVOKE</> commands in cases where <command>ALTER + DEFAULT PRIVILEGES</> had been used to reduce privileges to less than + they would normally be. + </para> + </listitem> + + <listitem> +<!-- +Author: Stephen Frost <[email protected]> +Branch: master [2259bf672] 2016-12-21 13:47:06 -0500 +Branch: REL9_6_STABLE [542975a14] 2016-12-21 13:47:13 -0500 +Branch: REL9_5_STABLE [1efc5dba0] 2016-12-21 13:47:18 -0500 +Branch: REL9_4_STABLE [13f51dacf] 2016-12-21 13:47:23 -0500 +Branch: REL9_3_STABLE [1f2cfd26f] 2016-12-21 13:47:28 -0500 +Branch: REL9_2_STABLE [da57166b7] 2016-12-21 13:47:32 -0500 +Branch: master [19990918d] 2016-12-21 13:47:06 -0500 +Branch: REL9_6_STABLE [e45319bb7] 2016-12-21 13:47:13 -0500 +Branch: REL9_5_STABLE [94476436a] 2016-12-21 13:47:18 -0500 +Branch: REL9_4_STABLE [107943f1a] 2016-12-21 13:47:23 -0500 +Branch: REL9_3_STABLE [fc03f7dd1] 2016-12-21 13:47:28 -0500 +Branch: REL9_2_STABLE [59a389891] 2016-12-21 13:47:32 -0500 +--> + <para> + Fix <application>pg_dump</> to dump user-defined casts and transforms + that use built-in functions (Stephen Frost) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [ac888986f] 2016-11-17 14:59:13 -0500 +Branch: REL9_6_STABLE [0eaa5118a] 2016-11-17 14:59:19 -0500 +Branch: REL9_5_STABLE [a7864037d] 2016-11-17 14:59:23 -0500 +Branch: REL9_4_STABLE [e69b532be] 2016-11-17 14:59:26 -0500 +--> + <para> + Fix <application>pg_restore</> with <option>--create --if-exists</> + to behave more sanely if an archive contains + unrecognized <command>DROP</> commands (Tom Lane) + </para> + + <para> + This doesn't fix any live bug, but it may improve the behavior in + future if <application>pg_restore</> is used with an archive + generated by a later <application>pg_dump</> version. + </para> + </listitem> + + <listitem> +<!-- +Author: Magnus Hagander <[email protected]> +Branch: master [10238fad0] 2016-12-19 10:11:04 +0100 +Branch: REL9_6_STABLE [1c8ad594e] 2016-12-19 10:15:52 +0100 +Branch: REL9_5_STABLE [bc53d7130] 2016-12-19 10:16:02 +0100 +Branch: REL9_4_STABLE [f6508827a] 2016-12-19 10:16:12 +0100 +--> + <para> + Fix <application>pg_basebackup</>'s rate limiting in the presence of + slow I/O (Antonin Houska) + </para> + + <para> + If disk I/O was transiently much slower than the specified rate + limit, the calculation overflowed, effectively disabling the rate + limit for the rest of the run. + </para> + </listitem> + + <listitem> +<!-- +Author: Magnus Hagander <[email protected]> +Branch: REL9_6_STABLE [b6a323a8c] 2016-11-07 14:47:30 +0100 +Branch: REL9_5_STABLE [6d779e05a] 2016-11-07 15:03:56 +0100 +Branch: REL9_4_STABLE [5556420d4] 2016-11-07 15:04:23 +0100 +--> + <para> + Fix <application>pg_basebackup</>'s handling of + symlinked <filename>pg_stat_tmp</> and <filename>pg_replslot</> + subdirectories (Magnus Hagander, Michael Paquier) + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [f267c1c24] 2016-10-27 11:19:51 -0400 +Branch: REL9_6_STABLE [05e2293f4] 2016-10-27 11:34:28 -0400 +Branch: REL9_5_STABLE [ef18cb7da] 2016-10-27 11:53:14 -0400 +Branch: REL9_4_STABLE [d1e9c8269] 2016-10-27 11:59:08 -0400 +Branch: REL9_3_STABLE [92929a3e3] 2016-10-27 12:00:05 -0400 +Branch: REL9_2_STABLE [629575fa2] 2016-10-27 12:14:07 -0400 +--> + <para> + Fix possible <application>pg_basebackup</> failure on standby + server when including WAL files (Amit Kapila, Robert Haas) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [dbdfd114f] 2016-11-25 18:36:10 -0500 +Branch: REL9_6_STABLE [255bcd27f] 2016-11-25 18:36:10 -0500 +--> + <para> + Improve <application>initdb</> to insert the correct + platform-specific default values for + the <replaceable>xxx</><literal>_flush_after</> parameters + into <filename>postgresql.conf</> (Fabien Coelho, Tom Lane) + </para> + + <para> + This is a cleaner way of documenting the default values than was used + previously. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [cd1b21569] 2016-12-22 15:01:37 -0500 +Branch: REL9_6_STABLE [77cd0dc7e] 2016-12-22 15:01:38 -0500 +Branch: REL9_5_STABLE [c472f2a33] 2016-12-22 15:01:39 -0500 +--> + <para> + Fix possible mishandling of expanded arrays in domain check + constraints and <literal>CASE</> execution (Tom Lane) + </para> + + <para> + It was possible for a PL/pgSQL function invoked in these contexts to + modify or even delete an array value that needs to be preserved for + additional operations. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [fc8b81a29] 2016-11-06 12:09:36 -0500 +Branch: REL9_6_STABLE [a5b153ff5] 2016-11-06 12:09:36 -0500 +Branch: REL9_5_STABLE [674877e93] 2016-11-06 12:09:36 -0500 +--> + <para> + Fix nested uses of PL/pgSQL functions in contexts such as domain + check constraints evaluated during assignment to a PL/pgSQL variable + (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [9cda81f00] 2016-12-09 15:27:23 -0500 +Branch: REL9_6_STABLE [b90f2247e] 2016-12-09 15:27:23 -0500 +Branch: REL9_5_STABLE [00858728f] 2016-12-09 15:27:23 -0500 +Branch: REL9_4_STABLE [13a4b37b9] 2016-12-09 15:27:23 -0500 +Branch: REL9_3_STABLE [cea6de20b] 2016-12-09 15:27:23 -0500 +Branch: REL9_2_STABLE [981885d17] 2016-12-09 15:27:23 -0500 +--> + <para> + Ensure that the Python exception objects we create for PL/Python are + properly reference-counted (Rafa de la Torre, Tom Lane) + </para> + + <para> + This avoids failures if the objects are used after a Python garbage + collection cycle has occurred. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [fd2664dcb] 2016-11-06 14:43:13 -0500 +Branch: REL9_6_STABLE [3af8467e9] 2016-11-06 14:43:13 -0500 +Branch: REL9_5_STABLE [abdc83998] 2016-11-06 14:43:13 -0500 +Branch: REL9_4_STABLE [110413a35] 2016-11-06 14:43:13 -0500 +Branch: REL9_3_STABLE [9c0b04f18] 2016-11-06 14:43:14 -0500 +Branch: REL9_2_STABLE [92b7b1058] 2016-11-06 14:43:14 -0500 +--> + <para> + Fix PL/Tcl to support triggers on tables that have <literal>.tupno</> + as a column name (Tom Lane) + </para> + + <para> + This matches the (previously undocumented) behavior of + PL/Tcl's <command>spi_exec</> and <command>spi_execp</> commands, + namely that a magic <literal>.tupno</> column is inserted only if + there isn't a real column named that. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [0a7481930] 2016-11-15 16:17:19 -0500 +Branch: REL9_6_STABLE [a69e6d9a6] 2016-11-15 16:17:19 -0500 +Branch: REL9_5_STABLE [8951f92da] 2016-11-15 16:17:19 -0500 +Branch: REL9_4_STABLE [e9802122d] 2016-11-15 16:17:19 -0500 +Branch: REL9_3_STABLE [46b6f3fff] 2016-11-15 16:17:19 -0500 +Branch: REL9_2_STABLE [13aa9af37] 2016-11-15 16:17:19 -0500 +--> + <para> + Allow DOS-style line endings in <filename>~/.pgpass</> files, + even on Unix (Vik Fearing) + </para> + + <para> + This change simplifies use of the same password file across Unix and + Windows machines. + </para> + </listitem> + + <listitem> +<!-- +Author: Michael Meskes <[email protected]> +Branch: master [4032ef18d] 2016-12-22 08:28:13 +0100 +Branch: REL9_6_STABLE [fd2a5547c] 2016-12-22 08:29:13 +0100 +Branch: REL9_5_STABLE [a88c547f9] 2016-12-22 08:29:33 +0100 +Branch: REL9_4_STABLE [3af172f7b] 2016-12-22 08:30:06 +0100 +Branch: REL9_3_STABLE [1df8b3fe8] 2016-12-22 08:32:25 +0100 +Branch: REL9_2_STABLE [501c91074] 2016-12-22 08:34:07 +0100 +--> + <para> + Fix one-byte buffer overrun if <application>ecpg</> is given a file + name that ends with a dot (Takayuki Tsunakawa) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [a3aef88e6] 2016-12-25 16:04:45 -0500 +Branch: REL9_6_STABLE [6a8c67f50] 2016-12-25 16:04:47 -0500 +--> + <para> + Fix incorrect error reporting for duplicate data + in <application>psql</>'s <command>\crosstabview</> (Tom Lane) + </para> + + <para> + <application>psql</> sometimes quoted the wrong row and/or column + values when complaining about multiple entries for the same crosstab + cell. + </para> + </listitem> + + <listitem> +<!-- +Author: Stephen Frost <[email protected]> +Branch: master [f3fd531a5] 2016-12-23 21:01:29 -0500 +Branch: REL9_6_STABLE [dc61580bd] 2016-12-23 21:01:33 -0500 +Branch: REL9_5_STABLE [16a2efdb2] 2016-12-23 21:01:40 -0500 +Branch: REL9_4_STABLE [98f30a0e7] 2016-12-23 21:01:45 -0500 +Branch: REL9_3_STABLE [2022d594d] 2016-12-23 21:01:48 -0500 +Branch: REL9_2_STABLE [26b55d669] 2016-12-23 21:01:51 -0500 +--> + <para> + Fix <application>psql</>'s tab completion for <command>ALTER DEFAULT + PRIVILEGES</> (Gilles Darold, Stephen Frost) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [404e66758] 2016-11-28 11:51:30 -0500 +Branch: REL9_6_STABLE [28735cc72] 2016-11-28 11:51:35 -0500 +--> + <para> + Fix <application>psql</>'s tab completion for <command>ALTER TABLE t + ALTER c DROP ...</> (Kyotaro Horiguchi) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [18f8f784c] 2016-12-07 12:19:56 -0500 +Branch: REL9_6_STABLE [bb39f58f7] 2016-12-07 12:19:56 -0500 +Branch: REL9_5_STABLE [370c7a863] 2016-12-07 12:19:56 -0500 +Branch: REL9_4_STABLE [ccb84dae1] 2016-12-07 12:19:56 -0500 +Branch: REL9_3_STABLE [82eb5c514] 2016-12-07 12:19:56 -0500 +Branch: REL9_2_STABLE [1ec5cc025] 2016-12-07 12:19:57 -0500 +--> + <para> + In <application>psql</>, treat an empty or all-blank setting of + the <envar>PAGER</> environment variable as meaning <quote>no + pager</> (Tom Lane) + </para> + + <para> + Previously, such a setting caused output intended for the pager to + vanish entirely. + </para> + </listitem> + + <listitem> +<!-- +Author: Joe Conway <[email protected]> +Branch: master [2f802d95b] 2016-12-22 09:48:55 -0800 +Branch: REL9_6_STABLE [51126ccdb] 2016-12-22 09:47:55 -0800 +Branch: REL9_5_STABLE [80ca22aa6] 2016-12-22 09:47:46 -0800 +Branch: REL9_4_STABLE [76943f54a] 2016-12-22 09:47:36 -0800 +Branch: REL9_3_STABLE [9b8507bfa] 2016-12-22 09:47:25 -0800 +Branch: REL9_2_STABLE [44de099f8] 2016-12-22 09:46:46 -0800 +--> + <para> + Improve <filename>contrib/dblink</>'s reporting of + low-level <application>libpq</> errors, such as out-of-memory + (Joe Conway) + </para> + </listitem> + + <listitem> +<!-- +Author: Joe Conway <[email protected]> +Branch: master [c44486838] 2016-12-22 09:20:35 -0800 +Branch: REL9_6_STABLE [150841fb9] 2016-12-22 09:19:34 -0800 +Branch: REL9_5_STABLE [d5c05f27a] 2016-12-22 09:19:18 -0800 +Branch: REL9_4_STABLE [cb687e0ac] 2016-12-22 09:19:08 -0800 +Branch: REL9_3_STABLE [bd46cce21] 2016-12-22 09:18:50 -0800 +--> + <para> + Teach <filename>contrib/dblink</> to ignore irrelevant server options + when it uses a <filename>contrib/postgres_fdw</> foreign server as + the source of connection options (Corey Huinker) + </para> + + <para> + Previously, if the foreign server object had options that were not + also <application>libpq</> connection options, an error occurred. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: REL9_6_STABLE [4774f6183] 2016-11-04 12:37:29 -0400 +Branch: REL9_5_STABLE [56d34ba5f] 2016-11-04 12:37:29 -0400 +Branch: master [14ee35799] 2016-11-02 00:09:27 -0400 +Branch: REL9_6_STABLE [2a8783e44] 2016-11-02 00:09:28 -0400 +Branch: REL9_5_STABLE [af636d7b5] 2016-11-02 00:09:28 -0400 +--> + <para> + Fix portability problems in <filename>contrib/pageinspect</>'s + functions for GIN indexes (Peter Eisentraut, Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [3b790d256] 2016-12-21 11:01:48 -0500 +Branch: REL9_6_STABLE [b98e5513f] 2016-12-21 11:11:36 -0500 +--> + <para> + Fix possible miss of socket read events while waiting on Windows + (Amit Kapila) + </para> + + <para> + This error was harmless for most uses, but it is known to cause hangs + when trying to use the pldebugger extension. + </para> + </listitem> + + <listitem> +<!-- +Author: Noah Misch <[email protected]> +Branch: master [95b9b8a39] 2016-12-03 15:46:36 -0500 +Branch: REL9_6_STABLE [784054579] 2016-12-03 15:46:42 -0500 +Branch: REL9_5_STABLE [5ab4b2ec4] 2016-12-03 15:46:48 -0500 +Branch: REL9_4_STABLE [b45a4949d] 2016-12-03 15:47:18 -0500 +Branch: REL9_3_STABLE [6c5d5918b] 2016-12-03 15:47:31 -0500 +Branch: REL9_2_STABLE [d83c94292] 2016-12-03 15:47:52 -0500 +Branch: master [b37da1e8a] 2016-12-03 15:46:35 -0500 +Branch: REL9_6_STABLE [056d62c5e] 2016-12-03 15:46:42 -0500 +Branch: REL9_5_STABLE [3cb8bdfef] 2016-12-03 15:46:48 -0500 +Branch: REL9_4_STABLE [ec7eacfae] 2016-12-03 15:47:12 -0500 +Branch: REL9_3_STABLE [4c3505eb4] 2016-12-03 15:47:31 -0500 +Branch: REL9_2_STABLE [a9265258a] 2016-12-03 15:47:49 -0500 +--> + <para> + On Windows, ensure that environment variable changes are propagated + to DLLs built with debug options (Christian Ullrich) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [93513d1b6] 2016-12-15 14:32:42 -0500 +Branch: REL9_6_STABLE [6f4d38dbe] 2016-12-15 14:32:58 -0500 +Branch: REL9_5_STABLE [492fe48f0] 2016-12-15 14:33:06 -0500 +Branch: REL9_4_STABLE [b95f4bf07] 2016-12-15 14:33:10 -0500 +Branch: REL9_3_STABLE [ccf24539b] 2016-12-15 14:33:14 -0500 +Branch: REL9_2_STABLE [2b7d715c0] 2016-12-15 14:33:19 -0500 +Branch: master [32416b0f9] 2016-11-06 10:45:58 -0500 +Branch: REL9_6_STABLE [20559a854] 2016-11-06 10:46:08 -0500 +Branch: REL9_5_STABLE [6e377ef0c] 2016-11-06 10:46:14 -0500 +Branch: REL9_4_STABLE [6651ab058] 2016-11-06 10:46:21 -0500 +Branch: REL9_3_STABLE [3a8f24abd] 2016-11-06 10:46:27 -0500 +Branch: REL9_2_STABLE [6653dbafd] 2016-11-06 10:46:34 -0500 +Branch: master [1f87181e1] 2016-11-03 22:24:34 -0400 +Branch: REL9_6_STABLE [7afafe8af] 2016-11-04 10:44:16 -0400 +Branch: REL9_5_STABLE [ac6fc1b55] 2016-11-04 10:44:16 -0400 +Branch: REL9_4_STABLE [c09478e15] 2016-11-04 10:44:16 -0400 +Branch: REL9_3_STABLE [22b1207a3] 2016-11-04 10:44:16 -0400 +Branch: REL9_2_STABLE [07bc2fc45] 2016-11-04 10:44:16 -0400 +--> + <para> + Sync our copy of the timezone library with IANA release tzcode2016j + (Tom Lane) + </para> + + <para> + This fixes various issues, most notably that timezone data + installation failed if the target directory didn't support hard + links. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [308d86827] 2017-01-30 11:40:22 -0500 +Branch: REL9_6_STABLE [6da67b684] 2017-01-30 11:40:39 -0500 +Branch: REL9_5_STABLE [4c729f471] 2017-01-30 11:40:46 -0500 +Branch: REL9_4_STABLE [a7b5de3ba] 2017-01-30 11:40:54 -0500 +Branch: REL9_3_STABLE [2b133be04] 2017-01-30 11:41:02 -0500 +Branch: REL9_2_STABLE [ef878cc2c] 2017-01-30 11:41:09 -0500 +--> + <para> + Update time zone data files to <application>tzdata</> release 2016j + for DST law changes in northern Cyprus (adding a new zone + Asia/Famagusta), Russia (adding a new zone Europe/Saratov), Tonga, + and Antarctica/Casey. + Historical corrections for Italy, Kazakhstan, Malta, and Palestine. + Switch to preferring numeric zone abbreviations for Tonga. + </para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + + <sect1 id="release-9-6-1"> + <title>Release 9.6.1</title> + + <formalpara> + <title>Release date:</title> + <para>2016-10-27</para> + </formalpara> + + <para> + This release contains a variety of fixes from 9.6.0. + For information about new features in the 9.6 major release, see + <xref linkend="release-9-6">. + </para> + + <sect2> + <title>Migration to Version 9.6.1</title> + + <para> + A dump/restore is not required for those running 9.6.X. + </para> + + <para> + However, if your installation has been affected by the bugs described in + the first two changelog entries below, then after updating you may need + to take action to repair corrupted free space maps and/or visibility + maps. + </para> + </sect2> + + <sect2> + <title>Changes</title> + + <itemizedlist> + + <listitem> +<!-- +Author: Heikki Linnakangas <[email protected]> +Branch: master [917dc7d23] 2016-10-19 14:26:05 +0300 +Branch: REL9_6_STABLE [142530ef0] 2016-10-19 14:43:34 +0300 +Branch: REL9_5_STABLE [b82573d6e] 2016-10-19 15:00:06 +0300 +Branch: REL9_4_STABLE [2523bef15] 2016-10-19 15:00:10 +0300 +Branch: REL9_3_STABLE [1c02ee314] 2016-10-19 15:00:34 +0300 +--> + <para> + Fix WAL-logging of truncation of relation free space maps and + visibility maps (Pavan Deolasee, Heikki Linnakangas) + </para> + + <para> + It was possible for these files to not be correctly restored during + crash recovery, or to be written incorrectly on a standby server. + Bogus entries in a free space map could lead to attempts to access + pages that have been truncated away from the relation itself, typically + producing errors like <quote>could not read block <replaceable>XXX</>: + read only 0 of 8192 bytes</quote>. Checksum failures in the + visibility map are also possible, if checksumming is enabled. + </para> + + <para> + Procedures for determining whether there is a problem and repairing it + if so are discussed at + <ulink url="https://wiki.postgresql.org/wiki/Free_Space_Map_Problems"></>. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [5afcd2aa7] 2016-09-30 20:40:55 -0400 +Branch: REL9_6_STABLE [b6d906073] 2016-09-30 20:39:06 -0400 +--> + <para> + Fix possible data corruption when <application>pg_upgrade</> rewrites + a relation visibility map into 9.6 format (Tom Lane) + </para> + + <para> + On big-endian machines, bytes of the new visibility map were written + in the wrong order, leading to a completely incorrect map. On + Windows, the old map was read using text mode, leading to incorrect + results if the map happened to contain consecutive bytes that matched + a carriage return/line feed sequence. The latter error would almost + always lead to a <application>pg_upgrade</> failure due to the map + file appearing to be the wrong length. + </para> + + <para> + If you are using a big-endian machine (many non-Intel architectures + are big-endian) and have used <application>pg_upgrade</> to upgrade + from a pre-9.6 release, you should assume that all visibility maps are + incorrect and need to be regenerated. It is sufficient to truncate + each relation's visibility map + with <filename>contrib/pg_visibility</>'s + <function>pg_truncate_visibility_map()</> function. + For more information see + <ulink url="https://wiki.postgresql.org/wiki/Visibility_Map_Problems"></>. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [a6c0a5b6e] 2016-10-23 18:36:13 -0400 +Branch: REL9_6_STABLE [c4016fcb1] 2016-10-23 18:36:13 -0400 +Branch: REL9_5_STABLE [65d85b8f9] 2016-10-23 18:36:13 -0400 +--> + <para> + Don't throw serialization errors for self-conflicting insertions + in <command>INSERT ... ON CONFLICT</> (Thomas Munro, Peter Geoghegan) + </para> + </listitem> + + <listitem> +<!-- +Author: Heikki Linnakangas <[email protected]> +Branch: master [d8589946d] 2016-10-17 12:13:16 +0300 +Branch: REL9_6_STABLE [a5f0bd77a] 2016-10-17 12:13:35 +0300 +--> + <para> + Fix use-after-free hazard in execution of aggregate functions + using <literal>DISTINCT</> (Peter Geoghegan) + </para> + + <para> + This could lead to a crash or incorrect query results. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [ac4a9d92f] 2016-10-09 12:49:37 -0400 +Branch: REL9_6_STABLE [dca25c256] 2016-10-09 12:49:37 -0400 +--> + <para> + Fix incorrect handling of polymorphic aggregates used as window + functions (Tom Lane) + </para> + + <para> + The aggregate's transition function was told that its first argument + and result were of the aggregate's output type, rather than the + state type. This led to errors or crashes with + polymorphic transition functions. + </para> + </listitem> + + <listitem> +<!-- +Author: Stephen Frost <[email protected]> +Branch: master [814b9e9b8] 2016-10-03 16:22:57 -0400 +Branch: REL9_6_STABLE [190765a05] 2016-10-03 16:23:02 -0400 +Branch: REL9_5_STABLE [647a86e37] 2016-10-03 16:23:12 -0400 +--> + <para> + Fix <command>COPY</> with a column name list from a table that has + row-level security enabled (Adam Brightwell) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [709e461be] 2016-10-20 17:17:50 -0400 +Branch: REL9_6_STABLE [033666515] 2016-10-20 17:17:57 -0400 +Branch: REL9_5_STABLE [cc0e4c567] 2016-10-20 17:18:01 -0400 +Branch: REL9_4_STABLE [adb199711] 2016-10-20 17:18:05 -0400 +Branch: REL9_3_STABLE [edb514306] 2016-10-20 17:18:09 -0400 +Branch: REL9_2_STABLE [f17c26dbd] 2016-10-20 17:18:14 -0400 +--> + <para> + Fix <command>EXPLAIN</> to emit valid XML when + <xref linkend="guc-track-io-timing"> is on (Markus Winand) + </para> + + <para> + Previously the XML output-format option produced syntactically invalid + tags such as <literal><I/O-Read-Time></>. That is now + rendered as <literal><I-O-Read-Time></>. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [81e82a2bd] 2016-10-13 19:46:05 -0400 +Branch: REL9_6_STABLE [03f2bf70a] 2016-10-13 19:46:06 -0400 +Branch: REL9_5_STABLE [3cd504254] 2016-10-13 19:45:58 -0400 +--> + <para> + Fix statistics update for <command>TRUNCATE</> in a prepared + transaction (Stas Kelvich) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [e55a946a8] 2016-10-08 19:29:27 -0400 +Branch: REL9_6_STABLE [b605aeba0] 2016-10-08 19:29:27 -0400 +Branch: REL9_5_STABLE [d1a9f128d] 2016-10-08 19:29:27 -0400 +Branch: REL9_4_STABLE [12230c478] 2016-10-08 19:29:27 -0400 +Branch: REL9_3_STABLE [56a047f46] 2016-10-08 19:29:28 -0400 +Branch: REL9_2_STABLE [a54faa659] 2016-10-08 19:29:28 -0400 +Branch: master [3cca13cbf] 2016-10-13 17:05:14 -0400 +Branch: REL9_6_STABLE [f9e8b05e5] 2016-10-13 17:05:14 -0400 +Branch: REL9_5_STABLE [3217ac3a9] 2016-10-13 17:05:15 -0400 +Branch: REL9_4_STABLE [f2024d59a] 2016-10-13 17:05:15 -0400 +Branch: REL9_3_STABLE [f0bf0f233] 2016-10-13 17:05:15 -0400 +Branch: REL9_2_STABLE [6f2db29ec] 2016-10-13 17:05:15 -0400 +--> + <para> + Fix bugs in merging inherited <literal>CHECK</> constraints while + creating or altering a table (Tom Lane, Amit Langote) + </para> + + <para> + Allow identical <literal>CHECK</> constraints to be added to a parent + and child table in either order. Prevent merging of a valid + constraint from the parent table with a <literal>NOT VALID</> + constraint on the child. Likewise, prevent merging of a <literal>NO + INHERIT</> child constraint with an inherited constraint. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [6bc811c99] 2016-10-03 16:40:25 -0400 +Branch: REL9_6_STABLE [993d94c59] 2016-10-03 16:40:26 -0400 +Branch: REL9_5_STABLE [f50fa46cc] 2016-10-03 16:40:27 -0400 +--> + <para> + Show a sensible value + in <structname>pg_settings</>.<structfield>unit</> + for <varname>min_wal_size</> and <varname>max_wal_size</> (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [9c4cc9e2c] 2016-10-13 00:25:48 -0400 +Branch: REL9_6_STABLE [0e9e64c07] 2016-10-13 00:25:28 -0400 +--> + <para> + Fix replacement of array elements in <function>jsonb_set()</> + (Tom Lane) + </para> + + <para> + If the target is an existing JSON array element, it got deleted + instead of being replaced with a new value. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [6292c2339] 2016-10-23 15:01:24 -0400 +Branch: REL9_6_STABLE [5beb73b49] 2016-10-23 15:01:24 -0400 +Branch: REL9_5_STABLE [913e7e598] 2016-10-23 15:01:24 -0400 +Branch: REL9_4_STABLE [9ec21591f] 2016-10-23 15:01:24 -0400 +Branch: REL9_3_STABLE [676c60375] 2016-10-23 15:01:24 -0400 +Branch: REL9_2_STABLE [9bc01e7a4] 2016-10-23 15:01:24 -0400 +Branch: REL9_1_STABLE [d4fa18a55] 2016-10-23 15:01:24 -0400 +Branch: master [8f1fb7d62] 2016-10-23 19:14:32 -0400 +Branch: REL9_6_STABLE [fdcee9f1f] 2016-10-23 19:14:32 -0400 +Branch: REL9_5_STABLE [beac79369] 2016-10-23 19:14:32 -0400 +--> + <para> + Avoid very-low-probability data corruption due to testing tuple + visibility without holding buffer lock (Thomas Munro, Peter Geoghegan, + Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Alvaro Herrera <[email protected]> +Branch: master [00f15338b] 2016-10-24 09:45:48 -0300 +Branch: REL9_6_STABLE [c8329f934] 2016-10-24 09:46:49 -0300 +Branch: REL9_5_STABLE [7a2fa5774] 2016-10-24 09:38:28 -0300 +--> + <para> + Preserve commit timestamps across server restart + (Julien Rouhaud, Craig Ringer) + </para> + + <para> + With <xref linkend="guc-track-commit-timestamp"> turned on, old + commit timestamps became inaccessible after a clean server restart. + </para> + </listitem> + + <listitem> +<!-- +Author: Andres Freund <[email protected]> +Branch: master [61633f790] 2016-10-03 22:11:36 -0700 +Branch: REL9_6_STABLE [76c0b73df] 2016-10-03 22:12:31 -0700 +Branch: REL9_5_STABLE [ce603a34a] 2016-10-03 22:13:10 -0700 +Branch: REL9_4_STABLE [07172b20f] 2016-10-03 22:14:12 -0700 +--> + <para> + Fix logical WAL decoding to work properly when a subtransaction's WAL + output is large enough to spill to disk (Andres Freund) + </para> + </listitem> + + <listitem> +<!-- +Author: Robert Haas <[email protected]> +Branch: master [308985b0b] 2016-09-28 11:19:46 -0400 +Branch: REL9_6_STABLE [32841fa32] 2016-09-28 11:22:39 -0400 +--> + <para> + Fix dangling-pointer problem in logical WAL decoding (Stas Kelvich) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [cb775768e] 2016-10-13 15:06:46 -0400 +Branch: REL9_6_STABLE [2dd9e315d] 2016-10-13 15:06:57 -0400 +Branch: REL9_5_STABLE [43d17489d] 2016-10-13 15:07:04 -0400 +Branch: REL9_4_STABLE [6d3cbbf59] 2016-10-13 15:07:11 -0400 +--> + <para> + Round shared-memory allocation request to a multiple of the actual + huge page size when attempting to use huge pages on Linux (Tom Lane) + </para> + + <para> + This avoids possible failures during <function>munmap()</> on systems + with atypical default huge page sizes. Except in crash-recovery + cases, there were no ill effects other than a log message. + </para> + </listitem> + + <listitem> +<!-- +Author: Heikki Linnakangas <[email protected]> +Branch: master [8bb14cdd3] 2016-10-07 12:20:39 +0300 +Branch: REL9_6_STABLE [341acf235] 2016-10-07 12:21:52 +0300 +Branch: REL9_5_STABLE [cb38c056f] 2016-10-07 12:22:19 +0300 +Branch: REL9_4_STABLE [31895abd8] 2016-10-07 12:22:45 +0300 +Branch: REL9_3_STABLE [fde92dc22] 2016-10-07 12:23:06 +0300 +Branch: REL9_2_STABLE [e7bb327e3] 2016-10-07 12:23:58 +0300 +Branch: REL9_1_STABLE [e76d06d7f] 2016-10-07 12:23:52 +0300 +Branch: master [275bf9860] 2016-10-07 12:51:52 +0300 +Branch: REL9_6_STABLE [4d3ecbfee] 2016-10-07 12:53:40 +0300 +Branch: REL9_5_STABLE [f0ca54037] 2016-10-07 12:53:42 +0300 +Branch: REL9_4_STABLE [418cd758a] 2016-10-07 12:53:45 +0300 +Branch: REL9_3_STABLE [b5afc6f67] 2016-10-07 12:53:47 +0300 +Branch: REL9_2_STABLE [5d5dc6f68] 2016-10-07 12:53:49 +0300 +Branch: REL9_1_STABLE [e84e4761f] 2016-10-07 12:53:51 +0300 +--> + <para> + Don't try to share SSL contexts across multiple connections + in <application>libpq</> (Heikki Linnakangas) + </para> + + <para> + This led to assorted corner-case bugs, particularly when trying to use + different SSL parameters for different connections. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [886f6c5cc] 2016-10-10 10:35:58 -0400 +Branch: REL9_6_STABLE [bb211b66f] 2016-10-10 10:35:58 -0400 +Branch: REL9_5_STABLE [4f87f7640] 2016-10-10 10:35:58 -0400 +Branch: REL9_4_STABLE [eb6bc03bf] 2016-10-10 10:35:58 -0400 +Branch: REL9_3_STABLE [455eaf984] 2016-10-10 10:35:58 -0400 +Branch: REL9_2_STABLE [7397f62e7] 2016-10-10 10:35:58 -0400 +Branch: REL9_1_STABLE [fb6825fe5] 2016-10-10 10:35:58 -0400 +--> + <para> + Avoid corner-case memory leak in <application>libpq</> (Tom Lane) + </para> + + <para> + The reported problem involved leaking an error report + during <function>PQreset()</>, but there might be related cases. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [83c249200] 2016-10-03 10:07:49 -0400 +Branch: REL9_6_STABLE [bac56dbe0] 2016-10-03 10:07:39 -0400 +Branch: REL9_5_STABLE [0f259bd17] 2016-10-03 10:07:39 -0400 +--> + <para> + In <application>pg_upgrade</>, check library loadability in name order + (Tom Lane) + </para> + + <para> + This is a workaround to deal with cross-extension dependencies from + language transform modules to their base language and data type + modules. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [e8bdee277] 2016-10-02 14:31:28 -0400 +Branch: REL9_6_STABLE [f40334b85] 2016-10-02 14:31:28 -0400 +--> + <para> + Fix <application>pg_upgrade</> to work correctly for extensions + containing index access methods (Tom Lane) + </para> + + <para> + To allow this, the server has been extended to support <command>ALTER + EXTENSION ADD/DROP ACCESS METHOD</>. That functionality should have + been included in the original patch to support dynamic creation of + access methods, but it was overlooked. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [f002ed2b8] 2016-09-30 20:40:56 -0400 +Branch: REL9_6_STABLE [53fbeed40] 2016-09-30 20:40:27 -0400 +--> + <para> + Improve error reporting in <application>pg_upgrade</>'s file + copying/linking/rewriting steps (Tom Lane, Álvaro Herrera) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [4806f26f9] 2016-10-07 09:51:18 -0400 +Branch: REL9_6_STABLE [1749332ec] 2016-10-07 09:51:28 -0400 +--> + <para> + Fix <application>pg_dump</> to work against pre-7.4 servers + (Amit Langote, Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Heikki Linnakangas <[email protected]> +Branch: master [0d4d7d618] 2016-10-07 14:35:17 +0300 +Branch: REL9_6_STABLE [2933ed036] 2016-10-07 14:35:41 +0300 +Branch: REL9_5_STABLE [010a1b561] 2016-10-07 14:35:45 +0300 +--> + <para> + Disallow specifying both <option>--source-server</> + and <option>--source-target</> options to <application>pg_rewind</> + (Michael Banck) + </para> + </listitem> + + <listitem> +<!-- +Author: Heikki Linnakangas <[email protected]> +Branch: master [d7eb76b90] 2016-10-06 13:24:46 +0300 +Branch: REL9_6_STABLE [aab809664] 2016-10-06 13:34:38 +0300 +Branch: REL9_5_STABLE [69da71254] 2016-10-06 13:34:32 +0300 +--> + <para> + Make <application>pg_rewind</> turn off <varname>synchronous_commit</> + in its session on the source server (Michael Banck, Michael Paquier) + </para> + + <para> + This allows <application>pg_rewind</> to work even when the source + server is using synchronous replication that is not working for some + reason. + </para> + </listitem> + + <listitem> +<!-- +Author: Magnus Hagander <[email protected]> +Branch: master [3d39244e6] 2016-09-30 11:22:00 +0200 +Branch: REL9_6_STABLE [41d58e97a] 2016-09-30 11:22:20 +0200 +Branch: REL9_5_STABLE [d8b4c3490] 2016-09-30 11:22:32 +0200 +Branch: REL9_4_STABLE [da3f71a08] 2016-09-30 11:22:49 +0200 +Branch: REL9_3_STABLE [4bff35cca] 2016-09-30 11:23:25 +0200 +--> + <para> + In <application>pg_xlogdump</>, retry opening new WAL segments when + using <option>--follow</> option (Magnus Hagander) + </para> + + <para> + This allows for a possible delay in the server's creation of the next + segment. + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [9a109452d] 2016-10-01 16:32:54 -0400 +Branch: REL9_6_STABLE [f4e787c82] 2016-10-01 16:32:55 -0400 +--> + <para> + Fix <filename>contrib/pg_visibility</> to report the correct TID for + a corrupt tuple that has been the subject of a rolled-back update + (Tom Lane) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [7107d58ec] 2016-10-01 13:35:13 -0400 +Branch: REL9_6_STABLE [68fb75e10] 2016-10-01 13:35:20 -0400 +--> + <para> + Fix makefile dependencies so that parallel make + of <application>PL/Python</> by itself will succeed reliably + (Pavel Raiskup) + </para> + </listitem> + + <listitem> +<!-- +Author: Tom Lane <[email protected]> +Branch: master [5e21b6811] 2016-10-20 15:40:07 -0400 +Branch: REL9_6_STABLE [845a8ea3e] 2016-10-20 15:40:14 -0400 +Branch: REL9_5_STABLE [aac898ac5] 2016-10-20 15:40:18 -0400 +Branch: REL9_4_STABLE [a8518738a] 2016-10-20 15:40:22 -0400 +Branch: REL9_3_STABLE [92da75278] 2016-10-20 15:40:26 -0400 +Branch: REL9_2_STABLE [b2aee4cb6] 2016-10-20 15:40:30 -0400 +Branch: REL9_1_STABLE [37ecf07d3] 2016-10-20 15:40:34 -0400 +Branch: master [d8fc45bd0] 2016-10-20 15:20:11 -0400 +Branch: REL9_6_STABLE [80ba149b0] 2016-10-20 15:20:17 -0400 +Branch: REL9_5_STABLE [8cddedc17] 2016-10-20 15:20:21 -0400 +Branch: REL9_4_STABLE [1d388ba2c] 2016-10-20 15:20:26 -0400 +Branch: REL9_3_STABLE [ff68f434f] 2016-10-20 15:20:30 -0400 +Branch: REL9_2_STABLE [3c5fae786] 2016-10-20 15:20:35 -0400 +Branch: REL9_1_STABLE [9345bf08c] 2016-10-20 15:20:39 -0400 +Branch: master [f3094920a] 2016-10-19 18:55:52 -0400 +Branch: REL9_6_STABLE [7fec5e101] 2016-10-19 18:55:57 -0400 +Branch: REL9_5_STABLE [bc59c1236] 2016-10-19 18:56:01 -0400 +Branch: REL9_4_STABLE [381c4b03b] 2016-10-19 18:56:05 -0400 +Branch: REL9_3_STABLE [ad6f67179] 2016-10-19 18:56:09 -0400 +Branch: REL9_2_STABLE [66adeefda] 2016-10-19 18:56:14 -0400 +Branch: REL9_1_STABLE [2877b102e] 2016-10-19 18:56:18 -0400 +Branch: master [ecbac3e6e] 2016-10-19 17:56:38 -0400 +Branch: REL9_6_STABLE [0c2f4c54c] 2016-10-19 17:56:45 -0400 +Branch: REL9_5_STABLE [5508d0c0b] 2016-10-19 17:56:49 -0400 +Branch: REL9_4_STABLE [9727dac58] 2016-10-19 17:56:53 -0400 +Branch: REL9_3_STABLE [7abda82ef] 2016-10-19 17:56:57 -0400 +Branch: REL9_2_STABLE [a03339aef] 2016-10-19 17:57:01 -0400 +Branch: REL9_1_STABLE [22cf97635] 2016-10-19 17:57:06 -0400 +--> + <para> + Update time zone data files to <application>tzdata</> release 2016h + for DST law changes in Palestine and Turkey, plus historical + corrections for Turkey and some regions of Russia. + Switch to numeric abbreviations for some time zones in Antarctica, + the former Soviet Union, and Sri Lanka. + </para> + + <para> + The IANA time zone database previously provided textual abbreviations + for all time zones, sometimes making up abbreviations that have little + or no currency among the local population. They are in process of + reversing that policy in favor of using numeric UTC offsets in zones + where there is no evidence of real-world use of an English + abbreviation. At least for the time being, <productname>PostgreSQL</> + will continue to accept such removed abbreviations for timestamp input. + But they will not be shown in the <structname>pg_timezone_names</> + view nor used for output. + </para> + + <para> + In this update, <literal>AMT</> is no longer shown as being in use to + mean Armenia Time. Therefore, we have changed the <literal>Default</> + abbreviation set to interpret it as Amazon Time, thus UTC-4 not UTC+4. + </para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + <sect1 id="release-9-6"> <title>Release 9.6</title> - <note> - <title>Release Date</title> - <simpara>2016-??-??</simpara> - <simpara>Current as of 2016-08-08 (commit 34927b292)</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2016-09-29</para> + </formalpara> <sect2> <title>Overview</title> @@ -23,40 +3154,40 @@ <listitem> <para> - Parallel sequential scans, joins and aggregates + Parallel execution of sequential scans, joins and aggregates </para> </listitem> <listitem> <para> - Eliminate repetitive scanning of old data by autovacuum + Avoid scanning pages unnecessarily during vacuum freeze operations </para> </listitem> <listitem> <para> - Synchronous replication now allows multiple standby servers, for + Synchronous replication now allows multiple standby servers for increased reliability </para> </listitem> <listitem> <para> - Allow full-text search for phrases (multiple adjacent words) + Full-text search can now search for phrases (multiple adjacent words) </para> </listitem> <listitem> <para> - Support foreign/remote joins, sorts, and <command>UPDATE</>s in - <filename>postgres_fdw</> + <filename>postgres_fdw</> now supports remote joins, sorts, + <command>UPDATE</>s, and <command>DELETE</>s </para> </listitem> <listitem> <para> Substantial performance improvements, especially in the area of - scalability on multi-<literal>CPU</>-socket servers + scalability on multi-<acronym>CPU</>-socket servers </para> </listitem> @@ -87,25 +3218,6 @@ <listitem> <!-- -2016-08-07 [d8710f18f] Correct column name in information schema ---> - <para> - Change the column name in the - <structname>information_schema</>.<structname>routines</> - view from <structfield>result_cast_character_set_name</> - to <structfield>result_cast_char_set_name</> (Clément - Prévost) - </para> - - <para> - The SQL:2011 standard specifies the longer name, but that appears - to be a mistake, because adjacent column names use the shorter - style, as do other <structname>information_schema</> views. - </para> - </listitem> - - <listitem> -<!-- 2016-03-10 [53be0b1ad] Provide much better wait information in pg_stat_activity --> <para> @@ -117,7 +3229,7 @@ <para> Historically a process has only been shown as waiting if it was - waiting for a heavy weight lock. Now waits for light weight locks + waiting for a heavyweight lock. Now waits for lightweight locks and buffer pins are also shown in <structname>pg_stat_activity</>. Also, the type of lock being waited for is now visible. These changes replace the <structfield>waiting</> column with @@ -149,18 +3261,18 @@ <para> Make <link linkend="functions-datetime-table"><function>extract()</></> behave - more reasonably with <literal>infinite</> inputs (Vitaly Burovoy) + more reasonably with infinite inputs (Vitaly Burovoy) </para> <para> Historically the <function>extract()</> function just returned zero given an infinite timestamp, regardless of the given - unit name. Make it return <literal>infinity</literal> + field name. Make it return <literal>infinity</literal> or <literal>-infinity</literal> as appropriate when the requested field is one that is monotonically increasing (e.g, <literal>year</>, <literal>epoch</>), or <literal>NULL</> when it is not (e.g., <literal>day</>, <literal>hour</>). Also, - throw the expected error for bad unit names. + throw the expected error for bad field names. </para> </listitem> @@ -186,8 +3298,8 @@ This commit is also listed under libpq and psql 2016-03-29 [61d66c44f] Fix support of digits in email/hostnames. --> <para> - Fix text search parser to allow leading digits in <literal>email</> - and <literal>host</> tokens (Artur Zakirov) + Fix the default text search parser to allow leading digits + in <literal>email</> and <literal>host</> tokens (Artur Zakirov) </para> <para> @@ -205,18 +3317,18 @@ This commit is also listed under libpq and psql 2016-03-16 [9a206d063] Improve script generating unaccent rules --> <para> - Extend <filename>contrib/unaccent</>'s standard - <filename>unaccent.rules</> file to handle all diacritics - known to Unicode, and expand ligatures correctly (Thomas Munro, + Extend <link linkend="unaccent"><filename>contrib/unaccent</></>'s + standard <filename>unaccent.rules</> file to handle all diacritics + known to Unicode, and to expand ligatures correctly (Thomas Munro, Léonard Benedetti) </para> <para> - The previous version omitted some less-common letters with - diacritic marks. It now also expands ligatures into separate - letters. Installations that use this rules file may wish to - rebuild <type>tsvector</> columns and indexes that depend on - the result. + The previous version neglected to convert some less-common letters + with diacritic marks. Also, ligatures are now expanded into + separate letters. Installations that use this rules file may wish + to rebuild <type>tsvector</> columns and indexes that depend on the + result. </para> </listitem> @@ -258,17 +3370,38 @@ This commit is also listed under libpq and psql <listitem> <!-- +2016-08-07 [d8710f18f] Correct column name in information schema +--> + <para> + Change a column name in the + <structname>information_schema</>.<structname>routines</> + view from <structfield>result_cast_character_set_name</> + to <structfield>result_cast_char_set_name</> (Clément + Prévost) + </para> + + <para> + The SQL:2011 standard specifies the longer name, but that appears + to be a mistake, because adjacent column names use the shorter + style, as do other <structname>information_schema</> views. + </para> + </listitem> + + <listitem> +<!-- 2015-12-08 [d5563d7df] psql: Support multiple -c and -f options, and allow mixi --> <para> - Support multiple <option>-c</option> and <option>-f</option> - command-line options (Pavel Stehule, Catalin Iacob) + <application>psql</>'s <option>-c</option> option no longer implies + <option>--no-psqlrc</option> + (Pavel Stehule, Catalin Iacob) </para> <para> - To allow this with sane behavior, one backwards incompatibility - had to be introduced: <option>-c</option> no longer implies - <option>--no-psqlrc</option>. + Write <option>--no-psqlrc</option> (or its + abbreviation <option>-X</option>) explicitly to obtain the old + behavior. Scripts so modified will still work with old + versions of <application>psql</>. </para> </listitem> @@ -277,7 +3410,7 @@ This commit is also listed under libpq and psql 2015-07-02 [5671aaca8] Improve pg_restore's -t switch to match all types of rel --> <para> - Improve <application>pg_restore</>'s <option>-t</option> switch to + Improve <application>pg_restore</>'s <option>-t</option> option to match all types of relations, not only plain tables (Craig Ringer) </para> </listitem> @@ -287,7 +3420,7 @@ This commit is also listed under libpq and psql 2016-02-12 [59a884e98] Change delimiter used for display of NextXID --> <para> - Change the display format of <literal>NextXID</> in + Change the display format used for <literal>NextXID</> in <application>pg_controldata</> and related places (Joe Conway, Bruce Momjian) </para> @@ -301,6 +3434,26 @@ This commit is also listed under libpq and psql </para> </listitem> + <listitem> +<!-- +2016-06-07 [a89b4b1be] Update citext extension for parallel query. +and many others in the same vein +--> + <para> + Update extension functions to be marked parallel-safe where + appropriate (Andreas Karlsson) + </para> + + <para> + Many of the standard extensions have been updated to allow their + functions to be executed within parallel query worker processes. + These changes will not take effect in + databases <application>pg_upgrade</>'d from prior versions unless + you apply <command>ALTER EXTENSION UPDATE</> to each such extension + (in each database of a cluster). + </para> + </listitem> + </itemizedlist> </sect2> @@ -348,6 +3501,8 @@ This commit is also listed under libpq and psql 2016-04-27 [59eb55127] Fix EXPLAIN VERBOSE output for parallel aggregate. 2016-06-09 [c9ce4a1c6] Eliminate "parallel degree" terminology. 2016-06-16 [75be66464] Invent min_parallel_relation_size GUC to replace a hard- +2016-08-16 [f85b1a841] Disable parallel query by default. +2016-09-15 [72ce78162] Make min_parallel_relation_size's default value platform --> <para> Parallel queries (Robert Haas, Amit Kapila, David Rowley, @@ -365,13 +3520,15 @@ This commit is also listed under libpq and psql </para> <para> - Use of parallel query execution can be controlled - through the new configuration parameters <xref - linkend="guc-max-parallel-workers-per-gather">, + Parallel query execution is not (yet) enabled by default. + To allow it, set the new configuration + parameter <xref linkend="guc-max-parallel-workers-per-gather"> to a + value larger than zero. Additional control over use of parallelism + is available through other new configuration parameters <xref linkend="guc-force-parallel-mode">, <xref linkend="guc-parallel-setup-cost">, <xref - linkend="guc-parallel-tuple-cost">, and <xref - linkend="guc-min-parallel-relation-size">. + linkend="guc-parallel-tuple-cost">, and + <literal>min_parallel_relation_size</literal>. </para> </listitem> @@ -380,8 +3537,8 @@ This commit is also listed under libpq and psql 2015-09-16 [7aea8e4f2] Determine whether it's safe to attempt a parallel plan f --> <para> - Provide infrastructure for marking the parallel-safe status of - functions (Robert Haas, Amit Kapila) + Provide infrastructure for marking the parallel-safety status of + functions (Robert Haas, Amit Kapila) </para> </listitem> @@ -401,7 +3558,7 @@ This commit is also listed under libpq and psql <para> Allow <link linkend="GIN"><acronym>GIN</></> index builds to make effective use of <xref linkend="guc-maintenance-work-mem"> - settings larger than 1GB (Robert Abraham, Teodor Sigaev) + settings larger than 1 GB (Robert Abraham, Teodor Sigaev) </para> </listitem> @@ -429,8 +3586,12 @@ This commit is also listed under libpq and psql Add <link linkend="functions-admin-index"><function>gin_clean_pending_list()</></> function to allow manual invocation of pending-list cleanup for a - GIN index, separately from vacuuming or analyzing the parent table - (Jeff Janes) + GIN index (Jeff Janes) + </para> + + <para> + Formerly, such cleanup happened only as a byproduct of vacuuming or + analyzing the parent table. </para> </listitem> @@ -467,222 +3628,186 @@ This commit is also listed under libpq and psql </sect4> <sect4> - <title>General Performance</title> + <title>Sorting</title> <itemizedlist> <listitem> <!-- -2016-03-01 [a892234f8] Change the format of the VM fork to add a second bit per -2016-03-08 [77a1d1e79] Department of second thoughts: remove PD_ALL_FROZEN. -2016-03-10 [fd31cd265] Don't vacuum all-frozen pages. -2016-03-11 [7087166a8] pg_upgrade: Convert old visibility map format to new for -2016-06-17 [ede62e56f] Add VACUUM (DISABLE_PAGE_SKIPPING) for emergencies. -2016-07-18 [eca0f1db1] Clear all-frozen visibilitymap status when locking tuple -2016-08-04 [e7caacf73] Fix hard to hit race condition in heapam's tuple locking +2016-04-08 [071180377] Use quicksort, not replacement selection, for external s +2016-03-17 [0011c0091] Improve memory management for external sorts. +2016-09-06 [96ba40c0f] Guard against possible memory allocation botch in batchm --> <para> - Avoid re-vacuuming pages containing only frozen tuples (Masahiko - Sawada, Robert Haas, Andres Freund) - </para> - - <para> - Formerly, anti-wraparound vacuum had to visit every page of - a table, even pages where there was nothing to do. Now, pages - containing only already-frozen tuples are identified in the table's - visibility map, and can be skipped by vacuum even when doing - transaction wraparound prevention. This should greatly reduce the - cost of maintaining large tables containing mostly-unchanged data. + Improve sorting performance by using quicksort, not replacement + selection sort, when performing external sort steps (Peter + Geoghegan) </para> <para> - If necessary, vacuum can be forced to process all-frozen - pages using the new <literal>DISABLE_PAGE_SKIPPING</> option. - Normally, this should never be needed but it might help in - recovering from visibility-map corruption. + The new approach makes better use of the <acronym>CPU</> cache + for typical cache sizes and data volumes. Where necessary, + the behavior can be adjusted via the new configuration parameter + <xref linkend="guc-replacement-sort-tuples">. </para> </listitem> <listitem> <!-- -2015-12-30 [e84290823] Avoid useless truncation attempts during VACUUM. +2015-10-09 [0e57b4d8b] Speed up text sorts where the same strings occur multipl +2015-10-20 [5be94a9eb] Be a bit more rigorous about how we cache strcoll and st --> <para> - Avoid useless heap-truncation attempts during <command>VACUUM</> - (Jeff Janes, Tom Lane) - </para> - - <para> - This change avoids taking an exclusive table lock in some cases - where no truncation is possible. The main benefit comes from - avoiding unnecessary query cancellations on standby servers. + Speed up text sorts where the same string occurs multiple times + (Peter Geoghegan) </para> </listitem> <listitem> <!-- -2016-01-09 [687f2cd7a] Avoid pin scan for replay of XLOG_BTREE_VACUUM -2016-04-03 [3e4b7d879] Avoid pin scan for replay of XLOG_BTREE_VACUUM in all ca +2015-11-06 [a76ef15d9] Add sort support routine for the UUID data type. +2016-02-03 [b47b4dbf6] Extend sortsupport for text to more opclasses. +2016-02-17 [f1f5ec1ef] Reuse abbreviated keys in ordered [set] aggregates. --> <para> - Reduce interlocking on standby servers during the replay of btree - index vacuuming operations (Simon Riggs) + Speed up sorting of <type>uuid</>, <type>bytea</>, and + <type>char(n)</> fields by using <quote>abbreviated</> keys + (Peter Geoghegan) </para> <para> - This change avoids substantial replication delays that sometimes - occurre while replaying such operations. + Support for abbreviated keys has also been + added to the non-default operator classes <link + linkend="indexes-opclass"><literal>text_pattern_ops</></>, + <literal>varchar_pattern_ops</>, and + <literal>bpchar_pattern_ops</>. Processing of ordered-set + aggregates can also now exploit abbreviated keys. </para> </listitem> <listitem> <!-- -2016-02-11 [d4c3a156c] Remove GROUP BY columns that are functionally dependent +2015-12-16 [b648b7034] Speed up CREATE INDEX CONCURRENTLY's TID sort. --> <para> - Avoid computing <literal>GROUP BY</> columns if they are - functionally dependent on other columns (David Rowley) - </para> - - <para> - If a <literal>GROUP BY</> clause includes all columns of a - non-deferred primary key, as well as other columns of the same - table, those other columns are redundant and can be dropped - from the grouping. This saves computation in many common cases. + Speed up <command>CREATE INDEX CONCURRENTLY</> by treating + <acronym>TID</>s as 64-bit integers during sorting (Peter + Geoghegan) </para> </listitem> + </itemizedlist> + + </sect4> + + <sect4> + <title>Locking</title> + + <itemizedlist> + <listitem> <!-- -2016-03-11 [9118d03a8] When appropriate, postpone SELECT output expressions til -2016-03-25 [d543170f2] Don't split up SRFs when choosing to postpone SELECT out +2015-08-06 [0e141c0fb] Reduce ProcArrayLock contention by removing backends in +2015-09-03 [4aec49899] Assorted code review for recent ProcArrayLock patch. --> <para> - When appropriate, postpone evaluation of <command>SELECT</> - output expressions until after an <literal>ORDER BY</> sort - (Konstantin Knizhnik) - </para> - - <para> - This change ensures that volatile or expensive functions in the - output list are executed in the order suggested by <literal>ORDER - BY</>, and that they are not evaluated more times than required - when there is a <literal>LIMIT</> clause. Previously, these - properties held if the ordering was performed by an index scan or - pre-merge-join sort, but not if it was performed by a top-level - sort. + Reduce contention for the <literal>ProcArrayLock</> (Amit Kapila, + Robert Haas) </para> </listitem> <listitem> <!-- -2016-03-10 [428b1d6b2] Allow to trigger kernel writeback after a configurable n -2016-04-13 [fa11a09fe] Fix assorted portability issues with using msync() for d -2016-04-24 [8f91d87d4] Fix documentation & config inconsistencies around 428b1d -2016-04-26 [72a98a639] Don't open formally non-existent segments in _mdfd_getse -2016-05-04 [a71248708] Fix transient mdsync() errors of truncated relations due -2016-02-16 [7975c5e0a] Allow the WAL writer to flush WAL at a reduced rate. -2016-06-10 [4bc0f165c] Change default of backend_flush_after GUC to 0 (disabled +2015-12-15 [6150a1b08] Move buffer I/O and content LWLocks out of the main tran --> <para> - Where feasible, trigger kernel writeback after a configurable - number of writes, to prevent accumulation of dirty data in kernel - disk buffers (Fabien Coelho, Andres Freund) + Improve performance by moving buffer content locks into the buffer + descriptors (Andres Freund, Simon Riggs) </para> + </listitem> + <listitem> +<!-- +2016-04-10 [48354581a] Allow Pin/UnpinBuffer to operate in a lockfree manner. +--> <para> - <productname>PostgreSQL</> writes data to the kernel's disk cache, - from where it will be flushed to physical storage in due time. - Many operating systems are not smart about managing this and allow - large amounts of dirty data to accumulate before deciding to flush - it all at once, leading to long delays for new I/O requests. - This change attempts to alleviate this problem by explicitly - requesting data flushes after a configurable interval. + Replace shared-buffer header spinlocks with atomic operations to + improve scalability (Alexander Korotkov, Andres Freund) </para> + </listitem> + <listitem> +<!-- +2016-04-10 [008608b9d] Avoid the use of a separate spinlock to protect a LWLock +--> <para> - On Linux, <function>sync_file_range()</> is used for this purpose, - and the feature is on by default on Linux because that function has few - downsides. This sync capability is also available on other platforms - that have <function>msync()</> or <function>posix_fadvise()</>, - but those interfaces have some undesirable side-effects so the - feature is disabled by default on non-Linux platforms. + Use atomic operations, rather than a spinlock, to protect an + <literal>LWLock</>'s wait queue (Andres Freund) </para> + </listitem> + <listitem> +<!-- +2016-03-23 [44ca4022f] Partition the freelist for shared dynahash tables. +--> <para> - The new configuration parameters <xref - linkend="guc-backend-flush-after">, <xref - linkend="guc-bgwriter-flush-after">, <xref - linkend="guc-checkpoint-flush-after">, and <xref - linkend="guc-wal-writer-flush-after"> control this behavior. + Partition the shared hash table freelist to reduce contention on + multi-<acronym>CPU</>-socket servers (Aleksander Alekseev) </para> </listitem> <listitem> <!-- -2016-03-10 [9cd00c457] Checkpoint sorting and balancing. +2016-01-09 [687f2cd7a] Avoid pin scan for replay of XLOG_BTREE_VACUUM +2016-04-03 [3e4b7d879] Avoid pin scan for replay of XLOG_BTREE_VACUUM in all ca --> <para> - Perform checkpoint writes in sorted order (Fabien Coelho, - Andres Freund) + Reduce interlocking on standby servers during the replay of btree + index vacuuming operations (Simon Riggs) </para> <para> - Previously, checkpoints wrote out dirty pages in whatever order - they happen to appear in shared buffers, which usually is nearly - random. That performs poorly, especially on rotating media. - This change causes checkpoint-driven writes to be done in order - by file and block number, and to be balanced across tablespaces. + This change avoids substantial replication delays that sometimes + occurred while replaying such operations. </para> </listitem> + </itemizedlist> + + </sect4> + + <sect4> + <title>Optimizer Statistics</title> + + <itemizedlist> + <listitem> <!-- -2016-04-08 [848ef42bb] Add the "snapshot too old" feature -2016-05-06 [2cc41acd8] Fix hash index vs "snapshot too old" problemms -2016-05-06 [7e3da1c47] Mitigate "snapshot too old" performance regression on NU -2016-08-03 [3e2f3c2e4] Prevent "snapshot too old" from trying to return pruned -2016-08-07 [9ee1cf04a] Fix TOAST access failure in RETURNING queries. +2016-04-01 [be4b4dc75] Omit null rows when applying the Haas-Stokes estimator f +2016-04-01 [3d3bf62f3] Omit null rows when setting the threshold for what's a m +2016-04-04 [391159e03] Partially revert commit 3d3bf62f30200500637b24fdb7b992a9 --> <para> - Allow old <acronym>MVCC</> snapshots to be invalidated after a - configurable timeout (Kevin Grittner) + Improve <command>ANALYZE</>'s estimates for columns with many nulls + (Tomas Vondra, Alex Shulgin) </para> <para> - Normally, deleted tuples cannot be physically removed by - vacuuming until the last transaction that could <quote>see</> - them is gone. A transaction that stays open for a long - time can thus cause considerable table bloat because - space cannot be recycled. This feature allows setting - a time-based limit, via the new configuration parameter - <xref linkend="guc-old-snapshot-threshold">, on how long an - <acronym>MVCC</> snapshot is guaranteed to be valid. After that, - dead tuples are candidates for removal. A transaction using an - outdated snapshot will get an error if it attempts to read a page - that potentially could have contained such data. + Previously <command>ANALYZE</> tended to underestimate the number + of non-<literal>NULL</> distinct values in a column with many + <literal>NULL</>s, and was also inaccurate in computing the + most-common values. </para> </listitem> <listitem> <!-- -2016-03-31 [f9aefcb91] Support using index-only scans with partial indexes in m +2016-04-04 [84f9a35e3] Improve estimate of distinct values in estimate_num_grou --> <para> - Allow use of an <link linkend="indexes-index-only-scans">index-only - scan</link> on a partial index when the index's <literal>WHERE</> - clause references columns which are not indexed (Tomas Vondra, - Kyotaro Horiguchi) - </para> - - <para> - For example, <command>CREATE INDEX tidx_partial ON t(b) WHERE a - > 0</> could not previously be used for an index-only scan by a - query that only referenced <literal>a</> in its <literal>WHERE</> - clause because <literal>a</> is not an indexed value like - <literal>b</> is. + Improve planner's estimate of the number of distinct values in + a query result (Tomas Vondra) </para> - </listitem> <listitem> @@ -701,7 +3826,7 @@ This commit is also listed under libpq and psql <literal>(a,b) REFERENCES r (x,y)</>, then a <literal>WHERE</> condition such as <literal>t.a = r.x AND t.b = r.y</> cannot select more than one <literal>r</> row per <literal>t</> row. - The planner formerly considered <literal>AND</> conditions + The planner formerly considered these <literal>AND</> conditions to be independent and would often drastically misestimate selectivity as a result. Now it compares the <literal>WHERE</> conditions to applicable foreign key constraints and produces @@ -709,267 +3834,321 @@ This commit is also listed under libpq and psql </para> </listitem> + </itemizedlist> + + </sect4> + + <sect4> + <title><command>VACUUM</></title> + + <itemizedlist> + <listitem> <!-- -2015-08-04 [804163bc2] Share transition state between different aggregates when +2016-03-01 [a892234f8] Change the format of the VM fork to add a second bit per +2016-03-08 [77a1d1e79] Department of second thoughts: remove PD_ALL_FROZEN. +2016-03-10 [fd31cd265] Don't vacuum all-frozen pages. +2016-03-11 [7087166a8] pg_upgrade: Convert old visibility map format to new for +2016-06-17 [ede62e56f] Add VACUUM (DISABLE_PAGE_SKIPPING) for emergencies. +2016-07-18 [eca0f1db1] Clear all-frozen visibilitymap status when locking tuple +2016-08-04 [e7caacf73] Fix hard to hit race condition in heapam's tuple locking --> <para> - Improve aggregate-function performance by sharing calculations - across multiple aggregates if they have the same arguments and - transition functions (David Rowley) + Avoid re-vacuuming pages containing only frozen tuples (Masahiko + Sawada, Robert Haas, Andres Freund) </para> <para> - For example, <command>SELECT AVG(x), SUM(x) FROM x</> can use a - single per-row compuation for both aggregates. + Formerly, anti-wraparound vacuum had to visit every page of + a table, even pages where there was nothing to do. Now, pages + containing only already-frozen tuples are identified in the table's + visibility map, and can be skipped by vacuum even when doing + transaction wraparound prevention. This should greatly reduce the + cost of maintaining large tables containing mostly-unchanging data. </para> - </listitem> - <listitem> -<!-- -2015-08-26 [8a7d07018] Speed up HeapTupleSatisfiesMVCC() by replacing the XID-i ---> <para> - Speed up visibility tests for recently-created tuples by checking - our transaction snapshot, not <structname>pg_clog</>, to decide - if the source transaction should be considered committed (Jeff - Janes, Tom Lane) + If necessary, vacuum can be forced to process all-frozen + pages using the new <literal>DISABLE_PAGE_SKIPPING</> option. + Normally this should never be needed, but it might help in + recovering from visibility-map corruption. </para> </listitem> <listitem> <!-- -2016-02-15 [db76b1efb] Allow SetHintBits() to succeed if the buffer's LSN is ne +2015-12-30 [e84290823] Avoid useless truncation attempts during VACUUM. --> <para> - Allow tuple hint bits to be set sooner than before (Andres Freund) + Avoid useless heap-truncation attempts during <command>VACUUM</> + (Jeff Janes, Tom Lane) + </para> + + <para> + This change avoids taking an exclusive table lock in some cases + where no truncation is possible. The main benefit comes from + avoiding unnecessary query cancellations on standby servers. </para> </listitem> + </itemizedlist> + + </sect4> + + <sect4> + <title>General Performance</title> + + <itemizedlist> + <listitem> <!-- -2016-01-20 [978b2f65a] Speedup 2PC by skipping two phase state files in normal -2016-03-10 [e0694cf9c] Reduce size of two phase file header +2016-04-08 [848ef42bb] Add the "snapshot too old" feature +2016-05-06 [2cc41acd8] Fix hash index vs "snapshot too old" problemms +2016-05-06 [7e3da1c47] Mitigate "snapshot too old" performance regression on NU +2016-08-03 [3e2f3c2e4] Prevent "snapshot too old" from trying to return pruned +2016-08-07 [9ee1cf04a] Fix TOAST access failure in RETURNING queries. --> <para> - Improve performance of short-lived prepared transactions (Stas - Kelvich, Simon Riggs, Pavan Deolasee) + Allow old <acronym>MVCC</> snapshots to be invalidated after a + configurable timeout (Kevin Grittner) </para> <para> - Two-phase commit information is now written only to <acronym>WAL</> - during <command>PREPARE TRANSACTION</>, and read from - <acronym>WAL</> during <command>COMMIT PREPARED</>. A separate - state file is created only if the pending transaction does not - get committed or aborted by the time of the next checkpoint. + Normally, deleted tuples cannot be physically removed by + vacuuming until the last transaction that could <quote>see</> + them is gone. A transaction that stays open for a long + time can thus cause considerable table bloat because + space cannot be recycled. This feature allows setting + a time-based limit, via the new configuration parameter + <xref linkend="guc-old-snapshot-threshold">, on how long an + <acronym>MVCC</> snapshot is guaranteed to be valid. After that, + dead tuples are candidates for removal. A transaction using an + outdated snapshot will get an error if it attempts to read a page + that potentially could have contained such data. </para> </listitem> <listitem> <!-- -2015-12-08 [25c539233] Improve performance in freeing memory contexts +2016-02-11 [d4c3a156c] Remove GROUP BY columns that are functionally dependent --> <para> - Improve performance of memory context destruction (Jan Wieck) + Ignore <literal>GROUP BY</> columns that are + functionally dependent on other columns (David Rowley) + </para> + + <para> + If a <literal>GROUP BY</> clause includes all columns of a + non-deferred primary key, as well as other columns of the same + table, those other columns are redundant and can be dropped + from the grouping. This saves computation in many common cases. </para> </listitem> <listitem> <!-- -2016-01-26 [cc988fbb0] Improve ResourceOwners' behavior for large numbers of ow +2016-03-31 [f9aefcb91] Support using index-only scans with partial indexes in m --> <para> - Improve performance of resource owners with many tracked objects - (Aleksander Alekseev) + Allow use of an <link linkend="indexes-index-only-scans">index-only + scan</link> on a partial index when the index's <literal>WHERE</> + clause references columns that are not indexed (Tomas Vondra, + Kyotaro Horiguchi) + </para> + + <para> + For example, an index defined by <command>CREATE INDEX tidx_partial + ON t(b) WHERE a > 0</> can now be used for an index-only scan by + a query that specifies <literal>WHERE a > 0</> and does not + otherwise use <literal>a</>. Previously this was disallowed + because <literal>a</> is not listed as an index column. </para> + </listitem> <listitem> <!-- -2016-02-06 [aa2387e2f] Improve speed of timestamp/time/date output functions. +2016-03-10 [9cd00c457] Checkpoint sorting and balancing. --> <para> - Improve speed of the output functions for <type>timestamp</>, - <type>time</>, and <type>date</> data types (David Rowley, + Perform checkpoint writes in sorted order (Fabien Coelho, Andres Freund) </para> - </listitem> - <listitem> -<!-- -2016-03-10 [37c54863c] Rework wait for AccessExclusiveLocks on Hot Standby ---> <para> - Avoid some unnecessary cancellations of hot-standby queries - during replay of actions that take <literal>AccessExclusive</> - locks (Jeff Janes) + Previously, checkpoints wrote out dirty pages in whatever order + they happen to appear in shared buffers, which usually is nearly + random. That performs poorly, especially on rotating media. + This change causes checkpoint-driven writes to be done in order + by file and block number, and to be balanced across tablespaces. </para> </listitem> <listitem> <!-- -2016-04-01 [be4b4dc75] Omit null rows when applying the Haas-Stokes estimator f -2016-04-01 [3d3bf62f3] Omit null rows when setting the threshold for what's a m -2016-04-04 [391159e03] Partially revert commit 3d3bf62f30200500637b24fdb7b992a9 +2016-03-10 [428b1d6b2] Allow to trigger kernel writeback after a configurable n +2016-04-13 [fa11a09fe] Fix assorted portability issues with using msync() for d +2016-04-24 [8f91d87d4] Fix documentation & config inconsistencies around 428b1d +2016-04-26 [72a98a639] Don't open formally non-existent segments in _mdfd_getse +2016-05-04 [a71248708] Fix transient mdsync() errors of truncated relations due +2016-02-16 [7975c5e0a] Allow the WAL writer to flush WAL at a reduced rate. +2016-06-10 [4bc0f165c] Change default of backend_flush_after GUC to 0 (disabled --> <para> - Improve <command>ANALYZE</>'s estimates for columns with many nulls - (Tomas Vondra, Alex Shulgin) + Where feasible, trigger kernel writeback after a configurable + number of writes, to prevent accumulation of dirty data in kernel + disk buffers (Fabien Coelho, Andres Freund) </para> <para> - Previously <command>ANALYZE</> tended to underestimate the number - of non-<literal>NULL</> distinct values in a column with many - <literal>NULL</>s, and was also inaccurate in computing the - most-common values. + <productname>PostgreSQL</> writes data to the kernel's disk cache, + from where it will be flushed to physical storage in due time. + Many operating systems are not smart about managing this and allow + large amounts of dirty data to accumulate before deciding to flush + it all at once, causing long delays for new I/O requests until the + flushing finishes. + This change attempts to alleviate this problem by explicitly + requesting data flushes after a configurable interval. </para> - </listitem> - <listitem> -<!-- -2016-04-04 [84f9a35e3] Improve estimate of distinct values in estimate_num_grou ---> <para> - Improve planner's estimate of the number of distinct values in - a query result (Tomas Vondra) + On Linux, <function>sync_file_range()</> is used for this purpose, + and the feature is on by default on Linux because that function has + few downsides. This flushing capability is also available on other + platforms if they have <function>msync()</> + or <function>posix_fadvise()</>, but those interfaces have some + undesirable side-effects so the feature is disabled by default on + non-Linux platforms. + </para> + + <para> + The new configuration parameters <xref + linkend="guc-backend-flush-after">, <xref + linkend="guc-bgwriter-flush-after">, <xref + linkend="guc-checkpoint-flush-after">, and <xref + linkend="guc-wal-writer-flush-after"> control this behavior. </para> </listitem> <listitem> <!-- -2016-04-08 [719c84c1b] Extend relations multiple blocks at a time to improve sc +2015-08-04 [804163bc2] Share transition state between different aggregates when --> <para> - Extend relations multiple blocks at a time when there is contention - for the relation's extension lock (Dilip Kumar) + Improve aggregate-function performance by sharing calculations + across multiple aggregates if they have the same arguments and + transition functions (David Rowley) </para> <para> - This improves scalability by decreasing contention. + For example, <command>SELECT AVG(x), VARIANCE(x) FROM tab</> can use + a single per-row computation for both aggregates. </para> </listitem> <listitem> <!-- -2016-04-08 [071180377] Use quicksort, not replacement selection, for external s -2016-03-17 [0011c0091] Improve memory management for external sorts. +2015-08-26 [8a7d07018] Speed up HeapTupleSatisfiesMVCC() by replacing the XID-i --> <para> - Improve sorting performance by using quicksort, not replacement - selection sort, when performing external sort steps (Peter - Geoghegan) - </para> - - <para> - The new approach makes better use of the <acronym>CPU</> cache - for typical cache sizes and data volumes. Where necessary, - the behavior can be adjusted via the new configuration parameter - <xref linkend="guc-replacement-sort-tuples">. + Speed up visibility tests for recently-created tuples by checking + the current transaction's snapshot, not <structname>pg_clog</>, to + decide if the source transaction should be considered committed + (Jeff Janes, Tom Lane) </para> </listitem> <listitem> <!-- -2015-10-09 [0e57b4d8b] Speed up text sorts where the same strings occur multipl -2015-10-20 [5be94a9eb] Be a bit more rigorous about how we cache strcoll and st +2016-02-15 [db76b1efb] Allow SetHintBits() to succeed if the buffer's LSN is ne --> <para> - Speed up text sorts where the same string occurs multiple times - (Peter Geoghegan) + Allow tuple hint bits to be set sooner than before (Andres Freund) </para> </listitem> <listitem> <!-- -2015-11-06 [a76ef15d9] Add sort support routine for the UUID data type. -2016-02-03 [b47b4dbf6] Extend sortsupport for text to more opclasses. -2016-02-17 [f1f5ec1ef] Reuse abbreviated keys in ordered [set] aggregates. +2016-01-20 [978b2f65a] Speedup 2PC by skipping two phase state files in normal +2016-03-10 [e0694cf9c] Reduce size of two phase file header --> <para> - Speed up sorting of <type>uuid</>, <type>bytea</>, and - <type>char(n)</> fields by using <quote>abbreviated</> keys - (Peter Geoghegan) + Improve performance of short-lived prepared transactions (Stas + Kelvich, Simon Riggs, Pavan Deolasee) </para> <para> - Support for abbreviated keys has also been - added to the non-default operator classes <link - linkend="indexes-opclass"><literal>text_pattern_ops</></>, - <literal>varchar_pattern_ops</>, and - <literal>bpchar_pattern_ops</>. Processing of ordered-set - aggregates can also now exploit abbreviated keys. + Two-phase commit information is now written only to <acronym>WAL</> + during <command>PREPARE TRANSACTION</>, and will be read back from + <acronym>WAL</> during <command>COMMIT PREPARED</> if that happens + soon thereafter. A separate state file is created only if the + pending transaction does not get committed or aborted by the time + of the next checkpoint. </para> </listitem> <listitem> <!-- -2015-12-16 [b648b7034] Speed up CREATE INDEX CONCURRENTLY's TID sort. +2015-12-08 [25c539233] Improve performance in freeing memory contexts --> <para> - Speed up <command>CREATE INDEX CONCURRENTLY</> by treating - <acronym>TID</>s as 64-bit integers during sorting (Peter - Geoghegan) + Improve performance of memory context destruction (Jan Wieck) </para> </listitem> <listitem> <!-- -2016-04-08 [5364b357f] Increase maximum number of clog buffers. +2016-01-26 [cc988fbb0] Improve ResourceOwners' behavior for large numbers of ow --> <para> - Increase the number of clog buffers for better scalability (Amit - Kapila, Andres Freund) + Improve performance of resource owners with many tracked objects + (Aleksander Alekseev) </para> </listitem> <listitem> <!-- -2015-08-06 [0e141c0fb] Reduce ProcArrayLock contention by removing backends in -2015-09-03 [4aec49899] Assorted code review for recent ProcArrayLock patch. +2016-02-06 [aa2387e2f] Improve speed of timestamp/time/date output functions. --> <para> - Reduce contention for the <literal>ProcArrayLock</> (Amit Kapila, - Robert Haas) + Improve speed of the output functions for <type>timestamp</>, + <type>time</>, and <type>date</> data types (David Rowley, + Andres Freund) </para> </listitem> <listitem> <!-- -2015-12-15 [6150a1b08] Move buffer I/O and content LWLocks out of the main tran +2016-03-10 [37c54863c] Rework wait for AccessExclusiveLocks on Hot Standby --> <para> - Improve performance by moving buffer content locks into the buffer - descriptors (Andres Freund, Simon Riggs) + Avoid some unnecessary cancellations of hot-standby queries + during replay of actions that take <literal>AccessExclusive</> + locks (Jeff Janes) </para> </listitem> <listitem> <!-- -2016-04-10 [48354581a] Allow Pin/UnpinBuffer to operate in a lockfree manner. +2016-04-08 [719c84c1b] Extend relations multiple blocks at a time to improve sc --> <para> - Replace shared-buffer header spinlocks with atomic operations to - improve scalability (Alexander Korotkov, Andres Freund) + Extend relations multiple blocks at a time when there is contention + for the relation's extension lock (Dilip Kumar) </para> - </listitem> - <listitem> -<!-- -2016-04-10 [008608b9d] Avoid the use of a separate spinlock to protect a LWLock ---> <para> - Use atomic operations, rather than a spinlock, to protect an - <literal>LWLock</>'s wait queue (Andres Freund) + This improves scalability by decreasing contention. </para> </listitem> <listitem> <!-- -2016-03-23 [44ca4022f] Partition the freelist for shared dynahash tables. +2016-04-08 [5364b357f] Increase maximum number of clog buffers. --> <para> - Partition the shared hash table freelist to reduce contention on - multi-<acronym>CPU</>-socket servers (Aleksander Alekseev) + Increase the number of clog buffers for better scalability (Amit + Kapila, Andres Freund) </para> </listitem> @@ -994,6 +4173,22 @@ This commit is also listed under libpq and psql </para> </listitem> + <listitem> +<!-- +2016-08-17 [9b33c7e80] Disable update_process_title by default on Windows +--> + <para> + Disable <xref linkend="guc-update-process-title"> by default on + Windows (Takayuki Tsunakawa) + </para> + + <para> + The overhead of updating the process title is much larger on Windows + than most other platforms, and it is also less useful to do it since + most Windows users do not have tools that can display process titles. + </para> + </listitem> + </itemizedlist> </sect4> @@ -1017,6 +4212,21 @@ This commit is also listed under libpq and psql <listitem> <!-- +2016-03-05 [dc7d70ea0] Expose control file data via SQL accessible functions. +--> + <para> + Add <link + linkend="functions-controldata"><function>pg_control_system()</></>, + <function>pg_control_checkpoint()</>, + <function>pg_control_recovery()</>, and + <function>pg_control_init()</> functions to expose fields of + <filename>pg_control</> to <acronym>SQL</> (Joe Conway, Michael + Paquier) + </para> + </listitem> + + <listitem> +<!-- 2016-02-17 [a5c43b886] Add new system view, pg_config --> <para> @@ -1026,7 +4236,7 @@ This commit is also listed under libpq and psql <para> This view exposes the same information available from - the the <application>pg_config</> comand-line utility, + the <application>pg_config</> command-line utility, namely assorted compile-time configuration information for <productname>PostgreSQL</>. </para> @@ -1072,9 +4282,9 @@ This commit is also listed under libpq and psql This function returns an array of the process IDs of any sessions that are blocking the session with the given process ID. Historically users have obtained such information using a self-join - on the <structname>pg_locks</> view. However, it is unreasonably + on the <structname>pg_locks</> view. However, it is unreasonably tedious to do it that way with any modicum of correctness, and - the addition of parallel queries has made the approach entirely + the addition of parallel queries has made the old approach entirely impractical, since locks might be held or awaited by child worker processes rather than the session's main process. </para> @@ -1082,21 +4292,6 @@ This commit is also listed under libpq and psql <listitem> <!-- -2016-03-05 [dc7d70ea0] Expose control file data via SQL accessible functions. ---> - <para> - Add <link - linkend="functions-controldata"><function>pg_control_system()</></>, - <function>pg_control_checkpoint()</>, - <function>pg_control_recovery()</>, and - <function>pg_control_init()</> functions to expose fields of - <filename>pg_control</> to <acronym>SQL</> (Joe Conway, Michael - Paquier) - </para> - </listitem> - - <listitem> -<!-- 2016-01-12 [e63bb4549] Add new user fn pg_current_xlog_flush_location() --> <para> @@ -1126,7 +4321,7 @@ This commit is also listed under libpq and psql </para> <para> - The memory usage dump output to the postmaster log during an + The memory usage dump that is output to the postmaster log during an out-of-memory failure now summarizes statistics when there are a large number of memory contexts, rather than possibly generating a very large report. There is also a <quote>grand total</> @@ -1148,7 +4343,8 @@ This commit is also listed under libpq and psql 2016-04-08 [34c33a1f0] Add BSD authentication method. --> <para> - Add an <literal>bsd</> authentication method to allow the use of + Add a <link linkend="auth-bsd"><acronym>BSD</> authentication + method</link> to allow use of the <systemitem class="osname">BSD</> Authentication service for <productname>PostgreSQL</> client authentication (Marisa Emerson) </para> @@ -1164,9 +4360,10 @@ This commit is also listed under libpq and psql 2016-04-08 [2f1d2b7a7] Set PAM_RHOST item for PAM authentication --> <para> - When using <acronym>PAM</> authentication, provide the client - IP address or host name to <acronym>PAM</> modules via the - <literal>PAM_RHOST</> item (Grzegorz Sampolski) + When using <link linkend="auth-pam"><acronym>PAM</> + authentication</link>, provide the client IP address or host name + to <acronym>PAM</> modules via the <literal>PAM_RHOST</> item + (Grzegorz Sampolski) </para> </listitem> @@ -1175,8 +4372,8 @@ This commit is also listed under libpq and psql 2016-01-07 [5e0b5dcab] Provide more detail in postmaster log for password authe --> <para> - Provide detail in the postmaster log during more password - authentication failures (Tom Lane) + Provide detail in the postmaster log for more types of password + authentication failure (Tom Lane) </para> <para> @@ -1190,8 +4387,8 @@ This commit is also listed under libpq and psql 2015-09-06 [643beffe8] Support RADIUS passwords up to 128 characters --> <para> - Support <acronym>RADIUS</> passwords up to 128 characters long - (Marko Tiikkaja) + Support <link linkend="auth-radius"><acronym>RADIUS</> passwords</> + up to 128 characters long (Marko Tiikkaja) </para> </listitem> @@ -1200,7 +4397,8 @@ This commit is also listed under libpq and psql 2016-04-08 [35e2e357c] Add authentication parameters compat_realm and upn_usena --> <para> - Add new <acronym>SSPI</> authentication parameters + Add new <link linkend="sspi-auth"><acronym>SSPI</> + authentication</link> parameters <varname>compat_realm</> and <varname>upn_username</> to control whether <productname>NetBIOS</> or <productname>Kerberos</> realm names and user names are used during <acronym>SSPI</> @@ -1219,46 +4417,39 @@ This commit is also listed under libpq and psql <listitem> <!-- -2016-02-02 [7d17e683f] Add support for systemd service notifications +2016-03-16 [c6dda1f48] Add idle_in_transaction_session_timeout. --> <para> - Add configure option <option>--with-systemd</> to enable - calling <function>sd_notify()</> at server start and stop (Peter - Eisentraut) + Allow sessions to be terminated automatically if they are in + idle-in-transaction state for too long (Vik Fearing) </para> <para> - This allows the use of <application>systemd</> service units of - type <literal>notify</>, which greatly simplifies the management - of <productname>PostgreSQL</> under <application>systemd</>. + This behavior is controlled by the new configuration parameter + <xref linkend="guc-idle-in-transaction-session-timeout">. It can + be useful to prevent forgotten transactions from holding locks + or preventing vacuum cleanup for too long. </para> </listitem> <listitem> <!-- -2015-09-08 [1aba62ec6] Allow per-tablespace effective_io_concurrency +2016-09-11 [f2dba881a] Raise max setting of checkpoint_timeout to 1d --> <para> - Allow <varname>effective_io_concurrency</> to be set per-tablespace - to support cases where different tablespaces have different I/O - characteristics (Julien Rouhaud) + Raise the maximum allowed value + of <xref linkend="guc-checkpoint-timeout"> to 24 hours (Simon Riggs) </para> </listitem> <listitem> <!-- -2016-03-16 [c6dda1f48] Add idle_in_transaction_session_timeout. +2015-09-08 [1aba62ec6] Allow per-tablespace effective_io_concurrency --> <para> - Allow sessions to be terminated automatically if they are in - idle-in-transaction state for too long (Vik Fearing) - </para> - - <para> - This behavior is controlled by the new configuration parameter - <xref linkend="guc-idle-in-transaction-session-timeout">. It can - be useful to prevent forgotten transactions from holding locks - or preventing vacuum cleanup for too long. + Allow <varname>effective_io_concurrency</> to be set per-tablespace + to support cases where different tablespaces have different I/O + characteristics (Julien Rouhaud) </para> </listitem> @@ -1268,9 +4459,9 @@ This commit is also listed under libpq and psql 2015-09-07 [b1e1862a1] Coordinate log_line_prefix options 'm' and 'n' to share --> <para> - Add <varname>log_line_prefix</> option <literal>%n</> to print - the current time as a Unix epoch, with milliseconds (Tomas Vondra, - Jeff Davis) + Add <xref linkend="guc-log-line-prefix"> option <literal>%n</> to + print the current time in Unix epoch form, with milliseconds (Tomas + Vondra, Jeff Davis) </para> </listitem> @@ -1299,9 +4490,26 @@ This commit is also listed under libpq and psql <para> Making a distinction between these settings is no longer useful, - and is part of a planned future simplification of replication - setup. The old names are still accepted but are converted - internally. + and merging them is a step towards a planned future simplification + of replication setup. The old names are still accepted but are + converted to <literal>replica</> internally. + </para> + </listitem> + + <listitem> +<!-- +2016-02-02 [7d17e683f] Add support for systemd service notifications +--> + <para> + Add configure option <option>--with-systemd</> to enable + calling <function>sd_notify()</> at server start and stop (Peter + Eisentraut) + </para> + + <para> + This allows the use of <application>systemd</> service units of + type <literal>notify</>, which greatly simplifies the management + of <productname>PostgreSQL</> under <application>systemd</>. </para> </listitem> @@ -1311,7 +4519,7 @@ This commit is also listed under libpq and psql --> <para> Allow the server's <acronym>SSL</> key file to have group read - access if owned by root (Christoph Berg) <!-- Windows handling? --> + access if it is owned by <literal>root</> (Christoph Berg) </para> <para> @@ -1352,8 +4560,8 @@ This commit is also listed under libpq and psql but that is unsafe and inefficient. It also prevents a new postmaster from being started until the last old backend has exited. Backends will detect postmaster death when waiting for - client I/O, so the exit will not be instantaneous, but it in most - cases should happen no later than the end of the current query. + client I/O, so the exit will not be instantaneous, but it should + happen no later than the end of the current query. </para> </listitem> @@ -1486,7 +4694,8 @@ XXX this is pending backpatch, may need to remove --> <para> Add a <option>--slot</option> option to - <application>pg_basebackup</> (Peter Eisentraut) + <link linkend="app-pgbasebackup"><application>pg_basebackup</></> + (Peter Eisentraut) </para> <para> @@ -1551,7 +4760,29 @@ XXX this is pending backpatch, may need to remove <para> Previously, such cases failed if the same target column was mentioned more than once, e.g., <literal>INSERT INTO tab (x[1], - x[2]) VALUES ...</>. + x[2]) VALUES (...)</>. + </para> + </listitem> + + <listitem> +<!-- +2016-03-11 [9118d03a8] When appropriate, postpone SELECT output expressions til +2016-03-25 [d543170f2] Don't split up SRFs when choosing to postpone SELECT out +--> + <para> + When appropriate, postpone evaluation of <command>SELECT</> + output expressions until after an <literal>ORDER BY</> sort + (Konstantin Knizhnik) + </para> + + <para> + This change ensures that volatile or expensive functions in the + output list are executed in the order suggested by <literal>ORDER + BY</>, and that they are not evaluated more times than required + when there is a <literal>LIMIT</> clause. Previously, these + properties held if the ordering was performed by an index scan or + pre-merge-join sort, but not if it was performed by a top-level + sort. </para> </listitem> @@ -1608,8 +4839,8 @@ XXX this is pending backpatch, may need to remove <para> Previously, the foreign join pushdown infrastructure left the question of security entirely up to individual foreign data - wrappers, but it would be too easy for an <acronym>FDW</> to - inadvertently open up subtle security hole. So, make it the core + wrappers, but that made it too easy for an <acronym>FDW</> to + inadvertently create subtle security holes. So, make it the core code's job to determine which role ID will access each table, and do not attempt join pushdown unless the role is the same for all relevant relations. @@ -1652,7 +4883,7 @@ XXX this is pending backpatch, may need to remove <para> This command allows a database object to be marked as depending - on an extension, so that it will be automatically dropped if + on an extension, so that it will be dropped automatically if the extension is dropped (without needing <literal>CASCADE</>). However, the object is not part of the extension, and thus will be dumped separately by <application>pg_dump</>. @@ -1710,9 +4941,9 @@ XXX this is pending backpatch, may need to remove 2016-03-23 [473b93287] Support CREATE ACCESS METHOD --> <para> - Introduce <command>CREATE ACCESS METHOD</> to allow extensions - to create index access methods (Alexander Korotkov, Petr - Jelínek) + Introduce <link linkend="sql-create-access-method"><command>CREATE + ACCESS METHOD</></> to allow extensions to create index access + methods (Alexander Korotkov, Petr Jelínek) </para> </listitem> @@ -1722,8 +4953,8 @@ XXX this is pending backpatch, may need to remove --> <para> Add a <literal>CASCADE</> option to <command>CREATE - EXTENSION</command> to automatically create extensions it depends - on (Petr Jelínek) + EXTENSION</command> to automatically create any extensions the + requested one depends on (Petr Jelínek) </para> </listitem> @@ -1748,7 +4979,7 @@ XXX this is pending backpatch, may need to remove </para> <para> - This is possible because the table has no existing rows. This matches + This is safe because the table has no existing rows. This matches the longstanding behavior of <literal>FOREIGN KEY</> constraints. </para> </listitem> @@ -1825,7 +5056,7 @@ XXX this is pending backpatch, may need to remove <para> Formerly, many security-sensitive functions contained hard-wired checks that would throw an error if they were called by a - non-superuser role. This forced the use of superuser roles for + non-superuser. This forced the use of superuser roles for some relatively pedestrian tasks. The hard-wired error checks are now gone in favor of making <application>initdb</> revoke the default public <literal>EXECUTE</> privilege on these functions. @@ -1844,6 +5075,11 @@ XXX this is pending backpatch, may need to remove that can be used to grant access to what were previously superuser-only functions (Stephen Frost) </para> + + <para> + Currently the only such role is <literal>pg_signal_backend</>, + but more are expected to be added in future. + </para> </listitem> </itemizedlist> @@ -1857,6 +5093,30 @@ XXX this is pending backpatch, may need to remove <listitem> <!-- +2016-04-07 [bb140506d] Phrase full text search. +2016-06-27 [028350f61] Make exact distance match for FTS phrase operator +2016-06-27 [3dbbd0f02] Do not fallback to AND for FTS phrase operator. +2016-06-27 [6734a1cac] Change predecence of phrase operator. +--> + <para> + Improve <link linkend="textsearch">full-text search</> to support + searching for phrases, that is, lexemes appearing adjacent to each + other in a specific order, or with a specified distance between + them (Teodor Sigaev, Oleg Bartunov, Dmitry Ivanov) + </para> + + <para> + A phrase-search query can be specified in <type>tsquery</> + input using the new operators <literal><-></> and + <literal><<replaceable>N</>></literal>. The former means + that the lexemes before and after it must appear adjacent to + each other in that order. The latter means they must be exactly + <replaceable>N</> lexemes apart. + </para> + </listitem> + + <listitem> +<!-- 2015-12-22 [6efbded6e] Allow omitting one or both boundaries in an array slice --> <para> @@ -1917,38 +5177,15 @@ XXX this is pending backpatch, may need to remove <listitem> <!-- -2016-04-07 [bb140506d] Phrase full text search. -2016-06-27 [028350f61] Make exact distance match for FTS phrase operator -2016-06-27 [3dbbd0f02] Do not fallback to AND for FTS phrase operator. -2016-06-27 [6734a1cac] Change predecence of phrase operator. ---> - <para> - Improve full-text search to support searching for phrases, that - is, lexemes appearing adjacent to each other in a specific order, - or with a specified distance between them (Teodor Sigaev, Oleg - Bartunov, Dmitry Ivanov) - </para> - - <para> - A phrase-search query can be specified in <type>tsquery</> - input using the new operators <literal><-></> and - <literal><<replaceable>N</>></literal>. The former means - that the lexemes before and after it must appear adjacent to - each other in that order. The latter means they must be exactly - <replaceable>N</> lexemes apart. - </para> - </listitem> - - <listitem> -<!-- 2016-03-04 [d78a7d9c7] Improve support of Hunspell in ispell dictionary. 2016-03-11 [8829af47e] Fix merge affixes for numeric ones 2016-03-17 [f4ceed6ce] Improve support of Hunspell --> <para> - Upgrade the <literal>ispell</> dictionary to handle modern - <productname>Hunspell</> files and support more languages - (Artur Zakirov) + Upgrade + the <link linkend="textsearch-ispell-dictionary"><literal>ispell</></> + dictionary type to handle modern <productname>Hunspell</> files and + support more languages (Artur Zakirov) </para> </listitem> @@ -1957,7 +5194,9 @@ XXX this is pending backpatch, may need to remove 2015-10-30 [12c9a0400] Implement lookbehind constraints in our regular-expressi --> <para> - Implement look-behind constraints in regular expressions (Tom Lane) + Implement look-behind constraints + in <link linkend="functions-posix-regexp">regular expressions</> + (Tom Lane) </para> <para> @@ -1989,7 +5228,7 @@ XXX this is pending backpatch, may need to remove 2015-11-07 [c5e86ea93] Add "xid <> xid" and "xid <> int4" operators. --> <para> - Add transaction id operators <type>xid</> <literal><></> + Add transaction ID operators <type>xid</> <literal><></> <type>xid</> and <type>xid</> <literal><></> <type>int4</>, for consistency with the corresponding equality operators (Michael Paquier) @@ -2035,8 +5274,10 @@ XXX this is pending backpatch, may need to remove 2016-01-05 [abb173392] Add scale(numeric) --> <para> - Add a <function>scale(numeric)</> function to extract the display - scale of a <type>numeric</> value (Marko Tiikkaja) + Add a <link + linkend="functions-math-func-table"><function>scale(numeric)</></> + function to extract the display scale of a <type>numeric</> value + (Marko Tiikkaja) </para> </listitem> @@ -2054,7 +5295,7 @@ XXX this is pending backpatch, may need to remove measures its argument in degrees, whereas <function>sin()</> measures in radians. These functions go to some lengths to deliver exact results for values where an exact result can be - expected, e.g. <literal>sind(30) = 0.5</literal>. + expected, for instance <literal>sind(30) = 0.5</literal>. </para> </listitem> @@ -2070,9 +5311,9 @@ XXX this is pending backpatch, may need to remove <para> The <acronym>POSIX</> standard says that these functions should - return <literal>NaN</> for NaN input, and should throw an error for - out-of-range inputs including <literal>infinity</>. Previously our - behavior varied across platforms. + return <literal>NaN</> for <literal>NaN</> input, and should throw + an error for out-of-range inputs including <literal>infinity</>. + Previously our behavior varied across platforms. </para> </listitem> @@ -2081,9 +5322,10 @@ XXX this is pending backpatch, may need to remove 2016-03-29 [e511d878f] Allow to_timestamp(float8) to convert float infinity to --> <para> - Make <function>to_timestamp(float8)</> convert float - <literal>infinity</> to timestamp <literal>infinity</> (Vitaly - Burovoy) + Make <link + linkend="functions-datetime-table"><function>to_timestamp(float8)</></> + convert float <literal>infinity</> to + timestamp <literal>infinity</> (Vitaly Burovoy) </para> <para> @@ -2115,11 +5357,12 @@ XXX this is pending backpatch, may need to remove 2015-09-17 [9acb9007d] Fix oversight in tsearch type check --> <para> - Allow <function>ts_stat_sql()</> and - <function>tsvector_update_trigger()</> to operate on values that - are of types binary-compatible with the expected argument type, - not just that argument type; for example allow <type>citext</> - where <type>text</> is expected (Teodor Sigaev) + Allow <link linkend="textsearch-statistics"><function>ts_stat()</></> + and <link linkend="textsearch-update-triggers"><function>tsvector_update_trigger()</></> + to operate on values that are of types binary-compatible with the + expected argument type, not just exactly that type; for example + allow <type>citext</> where <type>text</> is expected (Teodor + Sigaev) </para> </listitem> @@ -2161,8 +5404,9 @@ XXX this is pending backpatch, may need to remove <para> In <link linkend="functions-formatting-table"><function>to_number()</></>, - interpret <literal>V</> as dividing by 10 to the power of the - number of digits following <literal>V</> (Bruce Momjian) + interpret a <literal>V</> format code as dividing by 10 to the + power of the number of digits following <literal>V</> (Bruce + Momjian) </para> <para> @@ -2176,8 +5420,10 @@ XXX this is pending backpatch, may need to remove 2016-01-05 [ea0d494da] Make the to_reg*() functions accept text not cstring. --> <para> - Make the <function>to_reg*()</> functions accept type <type>text</> - not <type>cstring</> (Petr Korobeinikov) + Make the <link + linkend="functions-info-catalog-table"><function>to_reg*()</></> + functions accept type <type>text</> not <type>cstring</> + (Petr Korobeinikov) </para> <para> @@ -2234,7 +5480,7 @@ XXX this is pending backpatch, may need to remove <para> This allows avoiding an error for an unrecognized parameter - name, and instead return a <literal>NULL</>. + name, instead returning a <literal>NULL</>. </para> </listitem> @@ -2293,7 +5539,7 @@ XXX this is pending backpatch, may need to remove <para> In <link linkend="plpgsql">PL/pgSQL</link>, detect mismatched <command>CONTINUE</> and <command>EXIT</> statements while - compiling PL/pgSQL functions, rather than at execution time + compiling a function, rather than at execution time (Jim Nasby) </para> </listitem> @@ -2395,6 +5641,23 @@ XXX this is pending backpatch, may need to remove <listitem> <!-- +2016-08-26 [e796d0aba] Add a nonlocalized version of the severity field to clie +--> + <para> + Add a nonlocalized version of + the <link linkend="protocol-error-fields">severity field</> in + error and notice messages (Tom Lane) + </para> + + <para> + This change allows client code to determine severity of an error or + notice without having to worry about localized variants of the + severity strings. + </para> + </listitem> + + <listitem> +<!-- 2015-09-05 [0426f349e] Rearrange the handling of error context reports. This commit is also listed under psql and PL/pgSQL --> @@ -2424,6 +5687,8 @@ This commit is also listed under psql and PL/pgSQL </para> <para> + This is done with the new function <link + linkend="libpq-pqresultverboseerrormessage"><function>PQresultVerboseErrorMessage()</></>. This supports <application>psql</>'s new <literal>\errverbose</> feature, and may be useful for other clients as well. </para> @@ -2470,8 +5735,10 @@ This commit is also listed under psql and PL/pgSQL 2015-09-14 [d02426029] Check existency of table/schema for -t/-n option (pg_dum --> <para> - Add a <option>--strict-names</> option to <application>pg_dump</> - and <application>pg_restore</> (Pavel Stehule) + Add a <option>--strict-names</> option + to <link linkend="APP-PGDUMP"><application>pg_dump</></> + and <link linkend="APP-PGRESTORE"><application>pg_restore</></> + (Pavel Stehule) </para> <para> @@ -2505,10 +5772,26 @@ This commit is also listed under psql and PL/pgSQL <listitem> <!-- +2016-09-08 [31eb14504] Allow pg_dump to dump non-extension members of an extens +--> + <para> + Allow <application>pg_dump</> to dump non-extension-owned objects + that are within an extension-owned schema + (Martín Marqués) + </para> + + <para> + Previously such objects were ignored because they were mistakenly + assumed to belong to the extension owning their schema. + </para> + </listitem> + + <listitem> +<!-- 2016-04-06 [3b3fcc4ee] pg_dump: Add table qualifications to some tags --> <para> - In <application>pg_dump</>, include the table name in object + In <application>pg_dump</> output, include the table name in object tags for object types that are only uniquely named per-table (for example, triggers) (Peter Eisentraut) </para> @@ -2523,6 +5806,22 @@ This commit is also listed under psql and PL/pgSQL <listitem> <!-- +2015-12-08 [d5563d7df] psql: Support multiple -c and -f options, and allow mixi +this commit is also listed in the compatibility section +--> + <para> + Support multiple <option>-c</option> and <option>-f</option> + command-line options (Pavel Stehule, Catalin Iacob) + </para> + + <para> + The specified operations are carried out in the order in which the + options are given, and then <application>psql</> terminates. + </para> + </listitem> + + <listitem> +<!-- 2016-04-08 [c09b18f21] Support \crosstabview in psql --> <para> @@ -2608,7 +5907,7 @@ This commit is also listed under psql and PL/pgSQL 2016-06-15 [9901d8ac2] Use strftime("%c") to format timestamps in psql's \watch --> <para> - Improve the headers output of the <command>\watch</> command + Improve the headers output by the <command>\watch</> command (Michael Paquier, Tom Lane) </para> @@ -2719,8 +6018,9 @@ This commit is also listed under libpq and PL/pgSQL <para> This change allows SQL commands in scripts to span multiple lines. Existing custom scripts will need to be modified to add a semicolon - at the end of each line if missing. (Doing so does not break - the script for use with older versions of <application>pgbench</>.) + at the end of each line that does not have one already. (Doing so + does not break the script for use with older versions + of <application>pgbench</>.) </para> </listitem> @@ -2777,6 +6077,7 @@ This commit is also listed under libpq and PL/pgSQL <listitem> <!-- 2016-03-19 [7bafffea6] pgbench: Allow changing weights for scripts +2016-09-21 [970300faa] Print test parameters like "foo: 123", and results like --> <para> Allow changing the selection probabilities (weights) for scripts @@ -2823,7 +6124,7 @@ This commit is also listed under libpq and PL/pgSQL --> <para> Allow the number of client connections (<option>-c</>) to not - be an exact multiple of the number of threads (<option>-t</>) + be an exact multiple of the number of threads (<option>-j</>) (Fabien Coelho) </para> </listitem> @@ -2876,6 +6177,7 @@ This commit is also listed under libpq and PL/pgSQL <listitem> <!-- 2015-12-17 [c4a8812cf] Use just one standalone-backend session for initdb's pos +2016-08-30 [d9720e437] Fix initdb misbehavior when user mis-enters superuser pa --> <para> Speed up <application>initdb</> by using just one @@ -2889,8 +6191,9 @@ This commit is also listed under libpq and PL/pgSQL 2015-12-01 [e50cda784] Use pg_rewind when target timeline was switched --> <para> - Improve <application>pg_rewind</> so that it can work when the - target timeline changes (Alexander Korotkov) + Improve <link linkend="app-pgrewind"><application>pg_rewind</></> + so that it can work when the target timeline changes (Alexander + Korotkov) </para> <para> @@ -2921,6 +6224,25 @@ This commit is also listed under libpq and PL/pgSQL <listitem> <!-- +2016-08-27 [b9fe6cbc8] Add macros to make AllocSetContextCreate() calls simpler +--> + <para> + Add macros to make <function>AllocSetContextCreate()</> calls simpler + and safer (Tom Lane) + </para> + + <para> + Writing out the individual sizing parameters for a memory context + is now deprecated in favor of using one of the new + macros <symbol>ALLOCSET_DEFAULT_SIZES</>, + <symbol>ALLOCSET_SMALL_SIZES</>, + or <symbol>ALLOCSET_START_SMALL_SIZES</>. + Existing code continues to work, however. + </para> + </listitem> + + <listitem> +<!-- 2015-08-05 [de6fd1c89] Rely on inline functions even if that causes warnings in --> <para> @@ -3002,19 +6324,25 @@ This commit is also listed under libpq and PL/pgSQL <!-- 2016-01-17 [65c5fcd35] Restructure index access method API to hide most of it a 2016-01-21 [be44ed27b] Improve index AMs' opclass validation procedures. +2016-08-13 [ed0097e4f] Add SQL-accessible functions for inspecting index AM pro --> <para> - Restructure index access method <acronym>API</> to hide most of - it at the <application>C</> level (Alexander Korotkov) + Restructure <link linkend="indexam">index access + method <acronym>API</></> to hide most of it at + the <application>C</> level (Alexander Korotkov, Andrew Gierth) </para> <para> This change modernizes the index <acronym>AM API</> to look more like the designs we have adopted for foreign data wrappers and tablesample handlers. This simplifies the <application>C</> code - and should make it more feasible to define index access methods in + and makes it much more practical to define index access methods in installable extensions. A consequence is that most of the columns of the <structname>pg_am</> system catalog have disappeared. + New <link linkend="functions-info-catalog-table">inspection + functions</link> have been added to allow SQL queries to determine + index AM properties that used to be discoverable + from <structname>pg_am</>. </para> </listitem> @@ -3023,9 +6351,11 @@ This commit is also listed under libpq and PL/pgSQL 2016-04-06 [6c268df12] Add new catalog called pg_init_privs --> <para> - Add <structname>pg_init_privs</> system catalog to hold original - privileges of <application>initdb</>-created and extension-created - objects (Stephen Frost) + Add <link + linkend="catalog-pg-init-privs"><structname>pg_init_privs</></> + system catalog to hold original privileges + of <application>initdb</>-created and extension-created objects + (Stephen Frost) </para> <para> @@ -3220,7 +6550,7 @@ This commit is also listed under libpq and PL/pgSQL <para> This is somewhat like the <quote>reconstructed value</>, but it - could be any arbitrary chunk of data, it need not be of the same + could be any arbitrary chunk of data, not necessarily of the same data type as the indexed column. </para> </listitem> @@ -3257,6 +6587,16 @@ This commit is also listed under libpq and PL/pgSQL </para> </listitem> + <listitem> +<!-- +2016-09-15 [fcd93e4af] Support OpenSSL 1.1.0. +2016-09-15 [9895818d5] Fix building with LibreSSL. +--> + <para> + Support OpenSSL 1.1.0 (Andreas Karlsson, Heikki Linnakangas) + </para> + </listitem> + </itemizedlist> </sect3> @@ -3272,9 +6612,10 @@ This commit is also listed under libpq and PL/pgSQL 2016-03-13 [7a8d87483] Rename auto_explain.sample_ratio to sample_rate --> <para> - Add configuration parameter <literal>auto_explain.sample_rate</> - to allow <filename>contrib/auto_explain</> to capture just a - configurable fraction of all queries (Craig Ringer, Julien Rouhaud) + Add configuration parameter <literal>auto_explain.sample_rate</> to + allow <link linkend="auto-explain"><filename>contrib/auto_explain</></> + to capture just a configurable fraction of all queries (Craig + Ringer, Julien Rouhaud) </para> <para> @@ -3288,9 +6629,9 @@ This commit is also listed under libpq and PL/pgSQL 2016-04-01 [9ee014fc8] Bloom index contrib module --> <para> - Add <filename>contrib/bloom</> module that implements an index - access method based on Bloom filtering (Teodor Sigaev, Alexander - Korotkov) + Add <link linkend="bloom"><filename>contrib/bloom</></> module that + implements an index access method based on Bloom filtering (Teodor + Sigaev, Alexander Korotkov) </para> <para> @@ -3306,9 +6647,9 @@ This commit is also listed under libpq and PL/pgSQL 2015-12-28 [81ee726d8] Code and docs review for cube kNN support. --> <para> - In <filename>contrib/cube</>, introduce distance operators for - cubes, and support kNN-style searches in GiST indexes on cube - columns (Stas Kelvich) + In <link linkend="cube"><filename>contrib/cube</></>, introduce + distance operators for cubes, and support kNN-style searches in + GiST indexes on cube columns (Stas Kelvich) </para> </listitem> @@ -3339,8 +6680,9 @@ This commit is also listed under libpq and PL/pgSQL --> <para> Add selectivity estimation functions for - <filename>contrib/intarray</> operators to improve plans for - queries using those operators (Yury Zhuravlev, Alexander Korotkov) + <link linkend="intarray"><filename>contrib/intarray</></> operators + to improve plans for queries using those operators (Yury Zhuravlev, + Alexander Korotkov) </para> </listitem> @@ -3375,7 +6717,8 @@ This commit is also listed under libpq and PL/pgSQL --> <para> Add support for <quote>word similarity</> to - <filename>contrib/pg_trgm</> (Alexander Korotkov, Artur Zakirov) + <link linkend="pgtrgm"><filename>contrib/pg_trgm</></> + (Alexander Korotkov, Artur Zakirov) </para> <para> @@ -3391,9 +6734,8 @@ This commit is also listed under libpq and PL/pgSQL --> <para> Add configuration parameter - <varname>pg_trgm.similarity_threshold</> for <link - linkend="pgtrgm"><filename>contrib/pg_trgm</></>'s similarity - threshold (Artur Zakirov) + <varname>pg_trgm.similarity_threshold</> for + <filename>contrib/pg_trgm</>'s similarity threshold (Artur Zakirov) </para> <para> @@ -3430,8 +6772,9 @@ This commit is also listed under libpq and PL/pgSQL 2016-06-17 [71d05a2c7] pg_visibility: Add pg_truncate_visibility_map function. --> <para> - Add <filename>contrib/pg_visibility</> module to allow examining - table visibility maps (Robert Haas) + Add <link + linkend="pgvisibility"><filename>contrib/pg_visibility</></> module + to allow examining table visibility maps (Robert Haas) </para> </listitem> @@ -3450,7 +6793,7 @@ This commit is also listed under libpq and PL/pgSQL </itemizedlist> <sect4> - <title><filename>postgres_fdw</></title> + <title><link linkend="postgres-fdw"><filename>postgres_fdw</></></title> <itemizedlist> @@ -3502,7 +6845,7 @@ This commit is also listed under libpq and PL/pgSQL </para> <para> - Formerly, this involved sending a <command>SELECT FOR UPDATE</> + Formerly, remote updates involved sending a <command>SELECT FOR UPDATE</> command and then updating or deleting the selected rows one-by-one. While that is still necessary if the operation requires any local processing, it can now be done remotely if all elements of the @@ -3542,7 +6885,7 @@ This commit is also listed under libpq and PL/pgSQL --> <para> Transmit query cancellation requests to the remote server - (Michael Paquier) + (Michael Paquier, Etsuro Fujita) </para> <para> diff --git a/doc/src/sgml/release-old.sgml b/doc/src/sgml/release-old.sgml index ec8e43f6ea..d4de6b1357 100644 --- a/doc/src/sgml/release-old.sgml +++ b/doc/src/sgml/release-old.sgml @@ -4,10 +4,10 @@ <sect1 id="release-7-3-21"> <title>Release 7.3.21</title> - <note> - <title>Release Date</title> - <simpara>2008-01-07</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2008-01-07</para> + </formalpara> <para> This release contains a variety of fixes from 7.3.20, @@ -116,10 +116,10 @@ <sect1 id="release-7-3-20"> <title>Release 7.3.20</title> - <note> - <title>Release Date</title> - <simpara>2007-09-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-09-17</para> + </formalpara> <para> This release contains fixes from 7.3.19. @@ -177,10 +177,10 @@ <sect1 id="release-7-3-19"> <title>Release 7.3.19</title> - <note> - <title>Release Date</title> - <simpara>2007-04-23</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-04-23</para> + </formalpara> <para> This release contains fixes from 7.3.18, @@ -233,10 +233,10 @@ <sect1 id="release-7-3-18"> <title>Release 7.3.18</title> - <note> - <title>Release Date</title> - <simpara>2007-02-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-02-05</para> + </formalpara> <para> This release contains a variety of fixes from 7.3.17, including @@ -295,10 +295,10 @@ <sect1 id="release-7-3-17"> <title>Release 7.3.17</title> - <note> - <title>Release Date</title> - <simpara>2007-01-08</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2007-01-08</para> + </formalpara> <para> This release contains a variety of fixes from 7.3.16. @@ -351,10 +351,10 @@ <sect1 id="release-7-3-16"> <title>Release 7.3.16</title> - <note> - <title>Release Date</title> - <simpara>2006-10-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-10-16</para> + </formalpara> <para> This release contains a variety of fixes from 7.3.15. @@ -393,10 +393,10 @@ <sect1 id="release-7-3-15"> <title>Release 7.3.15</title> - <note> - <title>Release Date</title> - <simpara>2006-05-23</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-05-23</para> + </formalpara> <para> This release contains a variety of fixes from 7.3.14, @@ -485,10 +485,10 @@ Fuhr)</para></listitem> <sect1 id="release-7-3-14"> <title>Release 7.3.14</title> - <note> - <title>Release Date</title> - <simpara>2006-02-14</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-02-14</para> + </formalpara> <para> This release contains a variety of fixes from 7.3.13. @@ -542,10 +542,10 @@ and <function>isinf</> during configure (Tom)</para></listitem> <sect1 id="release-7-3-13"> <title>Release 7.3.13</title> - <note> - <title>Release Date</title> - <simpara>2006-01-09</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2006-01-09</para> + </formalpara> <para> This release contains a variety of fixes from 7.3.12. @@ -604,10 +604,10 @@ what's actually returned by the query (Joe)</para></listitem> <sect1 id="release-7-3-12"> <title>Release 7.3.12</title> - <note> - <title>Release Date</title> - <simpara>2005-12-12</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-12-12</para> + </formalpara> <para> This release contains a variety of fixes from 7.3.11. @@ -651,10 +651,10 @@ table has been dropped</para></listitem> <sect1 id="release-7-3-11"> <title>Release 7.3.11</title> - <note> - <title>Release Date</title> - <simpara>2005-10-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-10-04</para> + </formalpara> <para> This release contains a variety of fixes from 7.3.10. @@ -702,10 +702,10 @@ the variable is of pass-by-reference type</para></listitem> <sect1 id="release-7-3-10"> <title>Release 7.3.10</title> - <note> - <title>Release Date</title> - <simpara>2005-05-09</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-05-09</para> + </formalpara> <para> This release contains a variety of fixes from 7.3.9, including several @@ -828,10 +828,10 @@ month-related formats</para></listitem> <sect1 id="release-7-3-9"> <title>Release 7.3.9</title> - <note> - <title>Release Date</title> - <simpara>2005-01-31</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-01-31</para> + </formalpara> <para> This release contains a variety of fixes from 7.3.8, including several @@ -884,10 +884,10 @@ datestyles</para></listitem> <sect1 id="release-7-3-8"> <title>Release 7.3.8</title> - <note> - <title>Release Date</title> - <simpara>2004-10-22</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2004-10-22</para> + </formalpara> <para> This release contains a variety of fixes from 7.3.7. @@ -934,10 +934,10 @@ concern since there is no reason for non-developers to use this script anyway. <sect1 id="release-7-3-7"> <title>Release 7.3.7</title> - <note> - <title>Release Date</title> - <simpara>2004-08-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2004-08-16</para> + </formalpara> <para> This release contains one critical fix over 7.3.6, and some minor items. @@ -974,10 +974,10 @@ since <productname>PostgreSQL</productname> 7.1. <sect1 id="release-7-3-6"> <title>Release 7.3.6</title> - <note> - <title>Release Date</title> - <simpara>2004-03-02</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2004-03-02</para> + </formalpara> <para> This release contains a variety of fixes from 7.3.5. @@ -1039,10 +1039,10 @@ operations on bytea columns (Joe)</para></listitem> <sect1 id="release-7-3-5"> <title>Release 7.3.5</title> - <note> - <title>Release Date</title> - <simpara>2003-12-03</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2003-12-03</para> + </formalpara> <para> This has a variety of fixes from 7.3.4. @@ -1090,10 +1090,10 @@ operations on bytea columns (Joe)</para></listitem> <sect1 id="release-7-3-4"> <title>Release 7.3.4</title> - <note> - <title>Release Date</title> - <simpara>2003-07-24</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2003-07-24</para> + </formalpara> <para> This has a variety of fixes from 7.3.3. @@ -1130,10 +1130,10 @@ operations on bytea columns (Joe)</para></listitem> <sect1 id="release-7-3-3"> <title>Release 7.3.3</title> - <note> - <title>Release Date</title> - <simpara>2003-05-22</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2003-05-22</para> + </formalpara> <para> This release contains a variety of fixes for version 7.3.2. @@ -1240,10 +1240,10 @@ operations on bytea columns (Joe)</para></listitem> <sect1 id="release-7-3-2"> <title>Release 7.3.2</title> - <note> - <title>Release Date</title> - <simpara>2003-02-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2003-02-04</para> + </formalpara> <para> This release contains a variety of fixes for version 7.3.1. @@ -1301,10 +1301,10 @@ operations on bytea columns (Joe)</para></listitem> <sect1 id="release-7-3-1"> <title>Release 7.3.1</title> - <note> - <title>Release Date</title> - <simpara>2002-12-18</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2002-12-18</para> + </formalpara> <para> This release contains a variety of fixes for version 7.3. @@ -1351,10 +1351,10 @@ operations on bytea columns (Joe)</para></listitem> <sect1 id="release-7-3"> <title>Release 7.3</title> - <note> - <title>Release Date</title> - <simpara>2002-11-27</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2002-11-27</para> + </formalpara> <sect2> <title>Overview</title> @@ -1650,7 +1650,7 @@ operations on bytea columns (Joe)</para></listitem> <listitem><para>Add variable db_user_namespace for database-local user names (Bruce)</para></listitem> <listitem><para>SSL improvements (Bear Giles)</para></listitem> <listitem><para>Make encryption of stored passwords the default (Bruce)</para></listitem> -<listitem><para>Allow pg_statistics to be reset by calling pg_stat_reset() (Christopher)</para></listitem> +<listitem><para>Allow statistics collector to be reset by calling pg_stat_reset() (Christopher)</para></listitem> <listitem><para>Add log_duration parameter (Bruce)</para></listitem> <listitem><para>Rename debug_print_query to log_statement (Bruce)</para></listitem> <listitem><para>Rename show_query_stats to show_statement_stats (Bruce)</para></listitem> @@ -1987,10 +1987,10 @@ operations on bytea columns (Joe)</para></listitem> <sect1 id="release-7-2-8"> <title>Release 7.2.8</title> - <note> - <title>Release Date</title> - <simpara>2005-05-09</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-05-09</para> + </formalpara> <para> This release contains a variety of fixes from 7.2.7, including one @@ -2038,10 +2038,10 @@ month-related formats</para></listitem> <sect1 id="release-7-2-7"> <title>Release 7.2.7</title> - <note> - <title>Release Date</title> - <simpara>2005-01-31</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2005-01-31</para> + </formalpara> <para> This release contains a variety of fixes from 7.2.6, including several @@ -2086,10 +2086,10 @@ datestyles</para></listitem> <sect1 id="release-7-2-6"> <title>Release 7.2.6</title> - <note> - <title>Release Date</title> - <simpara>2004-10-22</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2004-10-22</para> + </formalpara> <para> This release contains a variety of fixes from 7.2.5. @@ -2137,10 +2137,10 @@ concern since there is no reason for non-developers to use this script anyway. <sect1 id="release-7-2-5"> <title>Release 7.2.5</title> - <note> - <title>Release Date</title> - <simpara>2004-08-16</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2004-08-16</para> + </formalpara> <para> This release contains a variety of fixes from 7.2.4. @@ -2180,10 +2180,10 @@ since <productname>PostgreSQL</productname> 7.1. <sect1 id="release-7-2-4"> <title>Release 7.2.4</title> - <note> - <title>Release Date</title> - <simpara>2003-01-30</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2003-01-30</para> + </formalpara> <para> This release contains a variety of fixes for version 7.2.3, @@ -2219,10 +2219,10 @@ since <productname>PostgreSQL</productname> 7.1. <sect1 id="release-7-2-3"> <title>Release 7.2.3</title> - <note> - <title>Release Date</title> - <simpara>2002-10-01</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2002-10-01</para> + </formalpara> <para> This release contains a variety of fixes for version 7.2.2, @@ -2256,10 +2256,10 @@ since <productname>PostgreSQL</productname> 7.1. <sect1 id="release-7-2-2"> <title>Release 7.2.2</title> - <note> - <title>Release Date</title> - <simpara>2002-08-23</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2002-08-23</para> + </formalpara> <para> This release contains a variety of fixes for version 7.2.1. @@ -2299,10 +2299,10 @@ since <productname>PostgreSQL</productname> 7.1. <sect1 id="release-7-2-1"> <title>Release 7.2.1</title> - <note> - <title>Release Date</title> - <simpara>2002-03-21</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2002-03-21</para> + </formalpara> <para> This release contains a variety of fixes for version 7.2. @@ -2345,10 +2345,10 @@ since <productname>PostgreSQL</productname> 7.1. <sect1 id="release-7-2"> <title>Release 7.2</title> - <note> - <title>Release Date</title> - <simpara>2002-02-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2002-02-04</para> + </formalpara> <sect2> <title>Overview</title> @@ -2901,10 +2901,10 @@ since <productname>PostgreSQL</productname> 7.1. <sect1 id="release-7-1-3"> <title>Release 7.1.3</title> - <note> - <title>Release Date</title> - <simpara>2001-08-15</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2001-08-15</para> + </formalpara> <sect2> <title>Migration to Version 7.1.3</title> @@ -2939,10 +2939,10 @@ Cygwin build (Jason Tishler) <sect1 id="release-7-1-2"> <title>Release 7.1.2</title> - <note> - <title>Release Date</title> - <simpara>2001-05-11</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2001-05-11</para> + </formalpara> <para> This has one fix from 7.1.1. @@ -2977,10 +2977,10 @@ pg_dump cleanups <sect1 id="release-7-1-1"> <title>Release 7.1.1</title> - <note> - <title>Release Date</title> - <simpara>2001-05-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2001-05-05</para> + </formalpara> <para> This has a variety of fixes from 7.1. @@ -3024,10 +3024,10 @@ Python fixes (Darcy) <sect1 id="release-7-1"> <title>Release 7.1</title> - <note> - <title>Release Date</title> - <simpara>2001-04-13</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2001-04-13</para> + </formalpara> <para> This release focuses on removing limitations that have existed in the @@ -3145,7 +3145,7 @@ Fix rare cursor crash when using hash join (Tom) Fix for DROP TABLE/INDEX in rolled-back transaction (Hiroshi) Fix psql crash from \l+ if MULTIBYTE enabled (Peter E) Fix truncation of rule names during CREATE VIEW (Ross Reedstrom) -Fix PL/perl (Alex Kapranoff) +Fix PL/Perl (Alex Kapranoff) Disallow LOCK on views (Mark Hollomon) Disallow INSERT/UPDATE/DELETE on views (Mark Hollomon) Disallow DROP RULE, CREATE INDEX, TRUNCATE on views (Mark Hollomon) @@ -3171,7 +3171,7 @@ Fix OVERLAPS operators conform to SQL92 spec regarding NULLs (Tom) Fix lpad() and rpad() to handle length less than input string (Tom) Fix use of NOTIFY in some rules (Tom) Overhaul btree code (Tom) -Fix NOT NULL use in Pl/pgSQL variables (Tom) +Fix NOT NULL use in PL/pgSQL variables (Tom) Overhaul GIST code (Oleg) Fix CLUSTER to preserve constraints and column default (Tom) Improved deadlock detection handling (Tom) @@ -3299,7 +3299,7 @@ New BeOS port (David Reid, Cyril Velter) Add proofreader's changes to docs (Addison-Wesley, Bruce) New Alpha spinlock code (Adriaan Joubert, Compaq) UnixWare port overhaul (Peter E) -New Darwin/Mac OS X port (Peter Bierman, Bruce Hartzler) +New macOS (Darwin) port (Peter Bierman, Bruce Hartzler) New FreeBSD Alpha port (Alfred) Overhaul shared memory segments (Tom) Add IBM S/390 support (Neale Ferguson) @@ -3322,10 +3322,10 @@ New FreeBSD tools ipc_check, start-scripts/freebsd <sect1 id="release-7-0-3"> <title>Release 7.0.3</title> - <note> - <title>Release Date</title> - <simpara>2000-11-11</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2000-11-11</para> + </formalpara> <para> This has a variety of fixes from 7.0.2. @@ -3394,10 +3394,10 @@ Fix for crash of backend, on abort (Tom) <sect1 id="release-7-0-2"> <title>Release 7.0.2</title> - <note> - <title>Release Date</title> - <simpara>2000-06-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2000-06-05</para> + </formalpara> <para> This is a repackaging of 7.0.1 with added documentation. @@ -3428,10 +3428,10 @@ Added documentation to tarball. <sect1 id="release-7-0-1"> <title>Release 7.0.1</title> - <note> - <title>Release Date</title> - <simpara>2000-06-01</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2000-06-01</para> + </formalpara> <para> This is a cleanup release for 7.0. @@ -3483,10 +3483,10 @@ ecpg changes (Michael) <sect1 id="release-7-0"> <title>Release 7.0</title> - <note> - <title>Release Date</title> - <simpara>2000-05-08</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>2000-05-08</para> + </formalpara> <para> This release contains improvements in many areas, demonstrating @@ -3893,7 +3893,7 @@ Faster sorting by calling fewer functions (Tom) Create system indexes to match all system caches (Bruce, Hiroshi) Make system caches use system indexes (Bruce) Make all system indexes unique (Bruce) -Improve pg_statistics management for VACUUM speed improvement (Tom) +Improve pg_statistic management for VACUUM speed improvement (Tom) Flush backend cache less frequently (Tom, Hiroshi) COPY now reuses previous memory allocation, improving performance (Tom) Improve optimization cost estimation (Tom) @@ -3952,10 +3952,10 @@ New multibyte encodings <sect1 id="release-6-5-3"> <title>Release 6.5.3</title> - <note> - <title>Release Date</title> - <simpara>1999-10-13</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1999-10-13</para> + </formalpara> <para> This is basically a cleanup release for 6.5.2. We have added a new @@ -3988,10 +3988,10 @@ Fix dumping rules on inherited tables <sect1 id="release-6-5-2"> <title>Release 6.5.2</title> - <note> - <title>Release Date</title> - <simpara>1999-09-15</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1999-09-15</para> + </formalpara> <para> This is basically a cleanup release for 6.5.1. We have fixed a variety of @@ -4045,10 +4045,10 @@ Updated version of pgaccess 0.98 <sect1 id="release-6-5-1"> <title>Release 6.5.1</title> - <note> - <title>Release Date</title> - <simpara>1999-07-15</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1999-07-15</para> + </formalpara> <para> This is basically a cleanup release for 6.5. We have fixed a variety of @@ -4100,10 +4100,10 @@ Add Win1250 (Czech) support (Pavel Behal) <sect1 id="release-6-5"> <title>Release 6.5</title> - <note> - <title>Release Date</title> - <simpara>1999-06-09</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1999-06-09</para> + </formalpara> <para> This release marks a major step in the development team's mastery of the source @@ -4341,7 +4341,7 @@ Fix for lo_import crash(Tatsuo) Adjust handling of data type names to suppress double quotes(Thomas) Use type coercion for matching columns and DEFAULT(Thomas) Fix deadlock so it only checks once after one second of sleep(Bruce) -Fixes for aggregates and PL/pgsql(Hiroshi) +Fixes for aggregates and PL/pgSQL(Hiroshi) Fix for subquery crash(Vadim) Fix for libpq function PQfnumber and case-insensitive names(Bahman Rafatjoo) Fix for large object write-in-middle, no extra block, memory consumption(Tatsuo) @@ -4500,10 +4500,10 @@ New install commands for plpgsql(Jan) <sect1 id="release-6-4-2"> <title>Release 6.4.2</title> - <note> - <title>Release Date</title> - <simpara>1998-12-20</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1998-12-20</para> + </formalpara> <para> The 6.4.1 release was improperly packaged. This also has one additional @@ -4535,10 +4535,10 @@ Fix for datetime constant problem on some platforms(Thomas) <sect1 id="release-6-4-1"> <title>Release 6.4.1</title> - <note> - <title>Release Date</title> - <simpara>1998-12-18</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1998-12-18</para> + </formalpara> <para> This is basically a cleanup release for 6.4. We have fixed a variety of @@ -4599,10 +4599,10 @@ Upgrade to PyGreSQL 2.2(D'Arcy) <sect1 id="release-6-4"> <title>Release 6.4</title> - <note> - <title>Release Date</title> - <simpara>1998-10-30</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1998-10-30</para> + </formalpara> <para> There are <emphasis>many</emphasis> new features and improvements in this release. @@ -4896,10 +4896,10 @@ new Makefile.shlib for shared library configuration(Tom) <sect1 id="release-6-3-2"> <title>Release 6.3.2</title> - <note> - <title>Release Date</title> - <simpara>1998-04-07</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1998-04-07</para> + </formalpara> <para> This is a bug-fix release for 6.3.x. @@ -4966,10 +4966,10 @@ ASSERT fixes(Bruce) <sect1 id="release-6-3-1"> <title>Release 6.3.1</title> - <note> - <title>Release Date</title> - <simpara>1998-03-23</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1998-03-23</para> + </formalpara> <para> Summary: @@ -5052,10 +5052,10 @@ Better identify tcl and tk libs and includes(Bruce) <sect1 id="release-6-3"> <title>Release 6.3</title> - <note> - <title>Release Date</title> - <simpara>1998-03-01</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1998-03-01</para> + </formalpara> <para> There are <emphasis>many</emphasis> new features and improvements in this release. @@ -5364,10 +5364,10 @@ Remove un-needed malloc() calls and replace with palloc()(Bruce) <sect1 id="release-6-2-1"> <title>Release 6.2.1</title> - <note> - <title>Release Date</title> - <simpara>1997-10-17</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1997-10-17</para> + </formalpara> <para> 6.2.1 is a bug-fix and usability release on 6.2. @@ -5446,10 +5446,10 @@ Trigger function for inserting user names for INSERT/UPDATE(Brook Milligan) <sect1 id="release-6-2"> <title>Release 6.2</title> - <note> - <title>Release Date</title> - <simpara>1997-10-02</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1997-10-02</para> + </formalpara> <para> A dump/restore is required for those wishing to migrate data from @@ -5599,10 +5599,10 @@ SPI and Trigger programming guides (Vadim & D'Arcy) <sect1 id="release-6-1-1"> <title>Release 6.1.1</title> - <note> - <title>Release Date</title> - <simpara>1997-07-22</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1997-07-22</para> + </formalpara> <sect2> <title>Migration from version 6.1 to version 6.1.1</title> @@ -5644,10 +5644,10 @@ pg_dumpall now returns proper status, portability fix(Bruce) <sect1 id="release-6-1"> <title>Release 6.1</title> - <note> - <title>Release Date</title> - <simpara>1997-06-08</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1997-06-08</para> + </formalpara> <para> The regression tests have been adapted and extensively modified for the @@ -5737,8 +5737,8 @@ fix rtree for use in inner scan (Vadim) fix gist for use in inner scan, cleanups (Vadim, Andrea) avoid unnecessary local buffers allocation (Vadim, Massimo) fix local buffers leak in transaction aborts (Vadim) -fix file manager memmory leaks, cleanups (Vadim, Massimo) -fix storage manager memmory leaks (Vadim) +fix file manager memory leaks, cleanups (Vadim, Massimo) +fix storage manager memory leaks (Vadim) fix btree duplicates handling (Vadim) fix deleted rows reincarnation caused by vacuum (Vadim) fix SELECT varchar()/char() INTO TABLE made zero-length fields(Bruce) @@ -5816,10 +5816,10 @@ DG/UX, Ultrix, IRIX, AIX portability fixes <sect1 id="release-6-0"> <title>Release 6.0</title> - <note> - <title>Release Date</title> - <simpara>1997-01-29</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1997-01-29</para> + </formalpara> <para> A dump/restore is required for those wishing to migrate data from @@ -5904,7 +5904,7 @@ European date format now set when postmaster is started Execute lowercase function names if not found with exact case Fixes for aggregate/GROUP processing, allow 'select sum(func(x),sum(x+y) from z' Gist now included in the distribution(Marc) -Idend authentication of local users(Bryan) +Ident authentication of local users(Bryan) Implement BETWEEN qualifier(Bruce) Implement IN qualifier(Bruce) libpq has PQgetisnull()(Bruce) @@ -5960,10 +5960,10 @@ Unused/uninitialized variables corrected <sect1 id="release-1-09"> <title>Release 1.09</title> - <note> - <title>Release Date</title> - <simpara>1996-11-04</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1996-11-04</para> + </formalpara> <para> Sorry, we didn't keep track of changes from 1.02 to 1.09. Some of @@ -5975,10 +5975,10 @@ releases. <sect1 id="release-1-02"> <title>Release 1.02</title> - <note> - <title>Release Date</title> - <simpara>1996-08-01</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1996-08-01</para> + </formalpara> <sect2> <title>Migration from version 1.02 to version 1.02.1</title> @@ -6124,10 +6124,10 @@ Contributors (apologies to any missed) <sect1 id="release-1-01"> <title>Release 1.01</title> - <note> - <title>Release Date</title> - <simpara>1996-02-23</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1996-02-23</para> + </formalpara> <sect2> @@ -6316,10 +6316,10 @@ Bug fixes: <sect1 id="release-1-0"> <title>Release 1.0</title> - <note> - <title>Release Date</title> - <simpara>1995-09-05</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1995-09-05</para> + </formalpara> <sect2> <title>Changes</title> @@ -6373,10 +6373,10 @@ Bug fixes: <sect1 id="release-0-03"> <title><productname>Postgres95</productname> Release 0.03</title> - <note> - <title>Release Date</title> - <simpara>1995-07-21</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1995-07-21</para> + </formalpara> <sect2> <title>Changes</title> @@ -6495,10 +6495,10 @@ New documentation: <sect1 id="release-0-02"> <title><productname>Postgres95</productname> Release 0.02</title> - <note> - <title>Release Date</title> - <simpara>1995-05-25</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1995-05-25</para> + </formalpara> <sect2> <title>Changes</title> @@ -6546,10 +6546,10 @@ The following bugs have been fixed in postgres95-beta-0.02: <sect1 id="release-0-01"> <title><productname>Postgres95</productname> Release 0.01</title> - <note> - <title>Release Date</title> - <simpara>1995-05-01</simpara> - </note> + <formalpara> + <title>Release date:</title> + <para>1995-05-01</para> + </formalpara> <para> Initial release. diff --git a/doc/src/sgml/release.sgml b/doc/src/sgml/release.sgml index eace76cace..7e3e2c5c44 100644 --- a/doc/src/sgml/release.sgml +++ b/doc/src/sgml/release.sgml @@ -9,12 +9,13 @@ postgresql.conf, pg_hba.conf, recovery.conf <filename> [A-Z][A-Z_ ]+[A-Z_] <command>, <literal>, <envar>, <acronym> [A-Za-z_][A-Za-z0-9_]+() <function> --[-A-Za-z_]+ <option> +\-\-?[A-Za-z_]+[-A-Za-z_]* <option> (use backslashes to avoid SGML markup) [A-Za-z_]+/[A-Za-z_]+ <filename> psql <application> pg_[A-Za-z0-9_]+ <application>, <structname> [A-Z][A-Z][A-Z_ ]* <type> -[a-z]+_[a-z_]+ <varname> +[a-z]+_[a-z_]+ <varname>, <structfield> + <systemitem class="osname"> non-ASCII characters find using grep -P '[\x80-\xFF]' convert to HTML4 named entity (&) escapes @@ -55,9 +56,9 @@ For new features, add links to the documentation sections. A complete list of changes for each release can be obtained by viewing the <link linkend="git">Git</link> logs for each release. The <ulink - url="http://archives.postgresql.org/pgsql-committers/"><literal>pgsql-committers</literal> + url="https://archives.postgresql.org/pgsql-committers/"><literal>pgsql-committers</literal> email list</ulink> records all source code changes as well. There is also - a <ulink url="http://git.postgresql.org/gitweb?p=postgresql.git;a=summary">web + a <ulink url="https://git.postgresql.org/gitweb?p=postgresql.git;a=summary">web interface</ulink> that shows changes to specific files. </para> @@ -73,6 +74,7 @@ For new features, add links to the documentation sections. The reason for splitting the release notes this way is so that appropriate subsets can easily be copied into back branches. --> +&release-10; &release-9.6; &release-xl-9.5r1; &release-9.5; diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml index 605dc71dab..9d6768e006 100644 --- a/doc/src/sgml/rowtypes.sgml +++ b/doc/src/sgml/rowtypes.sgml @@ -19,7 +19,7 @@ column of a table can be declared to be of a composite type. </para> - <sect2> + <sect2 id="rowtypes-declaring"> <title>Declaration of Composite Types</title> <para> @@ -90,7 +90,7 @@ CREATE TABLE inventory_item ( </sect2> <sect2> - <title>Composite Value Input</title> + <title>Constructing Composite Values</title> <indexterm> <primary>composite type</primary> @@ -101,8 +101,9 @@ CREATE TABLE inventory_item ( To write a composite value as a literal constant, enclose the field values within parentheses and separate them by commas. You can put double quotes around any field value, and must do so if it contains commas or - parentheses. (More details appear below.) Thus, the general format of a - composite constant is the following: + parentheses. (More details appear <link + linkend="rowtypes-io-syntax">below</link>.) Thus, the general format of + a composite constant is the following: <synopsis> '( <replaceable>val1</replaceable> , <replaceable>val2</replaceable> , ... )' </synopsis> @@ -129,7 +130,8 @@ CREATE TABLE inventory_item ( the generic type constants discussed in <xref linkend="sql-syntax-constants-generic">. The constant is initially treated as a string and passed to the composite-type input conversion - routine. An explicit type specification might be necessary.) + routine. An explicit type specification might be necessary to tell + which type to convert the constant to.) </para> <para> @@ -143,7 +145,7 @@ ROW('fuzzy dice', 42, 1.99) ROW('', 42, NULL) </programlisting> The ROW keyword is actually optional as long as you have more than one - field in the expression, so these can simplify to: + field in the expression, so these can be simplified to: <programlisting> ('fuzzy dice', 42, 1.99) ('', 42, NULL) @@ -153,7 +155,7 @@ ROW('', 42, NULL) </para> </sect2> - <sect2> + <sect2 id="rowtypes-accessing"> <title>Accessing Composite Types</title> <para> @@ -198,6 +200,11 @@ SELECT (my_func(...)).field FROM ... Without the extra parentheses, this will generate a syntax error. </para> + + <para> + The special field name <literal>*</> means <quote>all fields</>, as + further explained in <xref linkend="rowtypes-usage">. + </para> </sect2> <sect2> @@ -243,6 +250,199 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2); </para> </sect2> + <sect2 id="rowtypes-usage"> + <title>Using Composite Types in Queries</title> + + <para> + There are various special syntax rules and behaviors associated with + composite types in queries. These rules provide useful shortcuts, + but can be confusing if you don't know the logic behind them. + </para> + + <para> + In <productname>PostgreSQL</>, a reference to a table name (or alias) + in a query is effectively a reference to the composite value of the + table's current row. For example, if we had a table + <structname>inventory_item</> as shown + <link linkend="rowtypes-declaring">above</link>, we could write: +<programlisting> +SELECT c FROM inventory_item c; +</programlisting> + This query produces a single composite-valued column, so we might get + output like: +<programlisting> + c +------------------------ + ("fuzzy dice",42,1.99) +(1 row) +</programlisting> + Note however that simple names are matched to column names before table + names, so this example works only because there is no column + named <structfield>c</> in the query's tables. + </para> + + <para> + The ordinary qualified-column-name + syntax <replaceable>table_name</><literal>.</><replaceable>column_name</> + can be understood as applying <link linkend="field-selection">field + selection</link> to the composite value of the table's current row. + (For efficiency reasons, it's not actually implemented that way.) + </para> + + <para> + When we write +<programlisting> +SELECT c.* FROM inventory_item c; +</programlisting> + then, according to the SQL standard, we should get the contents of the + table expanded into separate columns: +<programlisting> + name | supplier_id | price +------------+-------------+------- + fuzzy dice | 42 | 1.99 +(1 row) +</programlisting> + as if the query were +<programlisting> +SELECT c.name, c.supplier_id, c.price FROM inventory_item c; +</programlisting> + <productname>PostgreSQL</> will apply this expansion behavior to + any composite-valued expression, although as shown <link + linkend="rowtypes-accessing">above</link>, you need to write parentheses + around the value that <literal>.*</> is applied to whenever it's not a + simple table name. For example, if <function>myfunc()</> is a function + returning a composite type with columns <structfield>a</>, + <structfield>b</>, and <structfield>c</>, then these two queries have the + same result: +<programlisting> +SELECT (myfunc(x)).* FROM some_table; +SELECT (myfunc(x)).a, (myfunc(x)).b, (myfunc(x)).c FROM some_table; +</programlisting> + </para> + + <tip> + <para> + <productname>PostgreSQL</> handles column expansion by + actually transforming the first form into the second. So, in this + example, <function>myfunc()</> would get invoked three times per row + with either syntax. If it's an expensive function you may wish to + avoid that, which you can do with a query like: +<programlisting> +SELECT (m).* FROM (SELECT myfunc(x) AS m FROM some_table OFFSET 0) ss; +</programlisting> + The <literal>OFFSET 0</> clause keeps the optimizer + from <quote>flattening</> the sub-select to arrive at the form with + multiple calls of <function>myfunc()</>. + </para> + </tip> + + <para> + The <replaceable>composite_value</><literal>.*</> syntax results in + column expansion of this kind when it appears at the top level of + a <link linkend="queries-select-lists"><command>SELECT</> output + list</link>, a <link linkend="dml-returning"><literal>RETURNING</> + list</link> in <command>INSERT</>/<command>UPDATE</>/<command>DELETE</>, + a <link linkend="queries-values"><literal>VALUES</> clause</link>, or + a <link linkend="sql-syntax-row-constructors">row constructor</link>. + In all other contexts (including when nested inside one of those + constructs), attaching <literal>.*</> to a composite value does not + change the value, since it means <quote>all columns</> and so the + same composite value is produced again. For example, + if <function>somefunc()</> accepts a composite-valued argument, + these queries are the same: + +<programlisting> +SELECT somefunc(c.*) FROM inventory_item c; +SELECT somefunc(c) FROM inventory_item c; +</programlisting> + + In both cases, the current row of <structname>inventory_item</> is + passed to the function as a single composite-valued argument. + Even though <literal>.*</> does nothing in such cases, using it is good + style, since it makes clear that a composite value is intended. In + particular, the parser will consider <literal>c</> in <literal>c.*</> to + refer to a table name or alias, not to a column name, so that there is + no ambiguity; whereas without <literal>.*</>, it is not clear + whether <literal>c</> means a table name or a column name, and in fact + the column-name interpretation will be preferred if there is a column + named <literal>c</>. + </para> + + <para> + Another example demonstrating these concepts is that all these queries + mean the same thing: +<programlisting> +SELECT * FROM inventory_item c ORDER BY c; +SELECT * FROM inventory_item c ORDER BY c.*; +SELECT * FROM inventory_item c ORDER BY ROW(c.*); +</programlisting> + All of these <literal>ORDER BY</> clauses specify the row's composite + value, resulting in sorting the rows according to the rules described + in <xref linkend="composite-type-comparison">. However, + if <structname>inventory_item</> contained a column + named <structfield>c</>, the first case would be different from the + others, as it would mean to sort by that column only. Given the column + names previously shown, these queries are also equivalent to those above: +<programlisting> +SELECT * FROM inventory_item c ORDER BY ROW(c.name, c.supplier_id, c.price); +SELECT * FROM inventory_item c ORDER BY (c.name, c.supplier_id, c.price); +</programlisting> + (The last case uses a row constructor with the key word <literal>ROW</> + omitted.) + </para> + + <para> + Another special syntactical behavior associated with composite values is + that we can use <firstterm>functional notation</> for extracting a field + of a composite value. The simple way to explain this is that + the notations <literal><replaceable>field</>(<replaceable>table</>)</> + and <literal><replaceable>table</>.<replaceable>field</></> + are interchangeable. For example, these queries are equivalent: + +<programlisting> +SELECT c.name FROM inventory_item c WHERE c.price > 1000; +SELECT name(c) FROM inventory_item c WHERE price(c) > 1000; +</programlisting> + + Moreover, if we have a function that accepts a single argument of a + composite type, we can call it with either notation. These queries are + all equivalent: + +<programlisting> +SELECT somefunc(c) FROM inventory_item c; +SELECT somefunc(c.*) FROM inventory_item c; +SELECT c.somefunc FROM inventory_item c; +</programlisting> + </para> + + <para> + This equivalence between functional notation and field notation + makes it possible to use functions on composite types to implement + <quote>computed fields</>. + <indexterm> + <primary>computed field</primary> + </indexterm> + <indexterm> + <primary>field</primary> + <secondary>computed</secondary> + </indexterm> + An application using the last query above wouldn't need to be directly + aware that <literal>somefunc</> isn't a real column of the table. + </para> + + <tip> + <para> + Because of this behavior, it's unwise to give a function that takes a + single composite-type argument the same name as any of the fields of + that composite type. If there is ambiguity, the field-name + interpretation will be preferred, so that such a function could not be + called without tricks. One way to force the function interpretation is + to schema-qualify the function name, that is, write + <literal><replaceable>schema</>.<replaceable>func</>(<replaceable>compositevalue</>)</literal>. + </para> + </tip> + </sect2> + <sect2 id="rowtypes-io-syntax"> <title>Composite Type Input and Output Syntax</title> diff --git a/doc/src/sgml/rules.sgml b/doc/src/sgml/rules.sgml index 5d7f8f8f73..ad9a6172e6 100644 --- a/doc/src/sgml/rules.sgml +++ b/doc/src/sgml/rules.sgml @@ -868,7 +868,7 @@ SELECT t1.a, t2.b, t1.ctid FROM t1, t2 WHERE t1.a = t2.a; <command>UPDATE</command>, and <command>DELETE</command> commands on a view. These rules will rewrite the command, typically into a command that updates one or more tables, rather than views. That is the topic - of the next section. + of <xref linkend="rules-update">. </para> <para> diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index 714d29c463..bafb099ccd 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -207,7 +207,7 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput> </para> <para> - Non-<literal>C</> and and non-<literal>POSIX</> locales rely on the + Non-<literal>C</> and non-<literal>POSIX</> locales rely on the operating system's collation library for character set ordering. This controls the ordering of keys stored in indexes. For this reason, a cluster cannot switch to an incompatible collation library version, @@ -1032,9 +1032,9 @@ su - postgres -c "/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgs <para> <screen> -LOG: could not bind IPv4 socket: Address already in use +LOG: could not bind IPv4 address "127.0.0.1": Address already in use HINT: Is another postmaster already running on port 5432? If not, wait a few seconds and retry. -FATAL: could not create TCP/IP listen socket +FATAL: could not create any TCP/IP sockets </screen> This usually means just what it suggests: you tried to start another server on the same port where one is already running. @@ -1044,9 +1044,9 @@ FATAL: could not create TCP/IP listen socket on a reserved port number might draw something like: <screen> $ <userinput>postgres -p 666</userinput> -LOG: could not bind IPv4 socket: Permission denied +LOG: could not bind IPv4 address "127.0.0.1": Permission denied HINT: Is another postmaster already running on port 666? If not, wait a few seconds and retry. -FATAL: could not create TCP/IP listen socket +FATAL: could not create any TCP/IP sockets </screen> </para> @@ -1173,27 +1173,47 @@ psql: could not connect to server: No such file or directory </indexterm> <para> - Shared memory and semaphores are collectively referred to as - <quote><systemitem class="osname">System V</> - <acronym>IPC</></quote> (together with message queues, which are not - relevant for <productname>PostgreSQL</>). Except on - <systemitem class="osname">Windows</>, where <productname>PostgreSQL</> - provides its own replacement implementation of these facilities, these - facilities are required in order to run - <productname>PostgreSQL</>. + <productname>PostgreSQL</> requires the operating system to provide + inter-process communication (<acronym>IPC</>) features, specifically + shared memory and semaphores. Unix-derived systems typically provide + <quote><systemitem class="osname">System V</></> <acronym>IPC</>, + <quote><systemitem class="osname">POSIX</></> <acronym>IPC</>, or both. + <systemitem class="osname">Windows</> has its own implementation of + these features and is not discussed here. </para> <para> The complete lack of these facilities is usually manifested by an - <errorname>Illegal system call</> error upon server start. In - that case there is no alternative but to reconfigure your + <quote><errorname>Illegal system call</></quote> error upon server + start. In that case there is no alternative but to reconfigure your kernel. <productname>PostgreSQL</> won't work without them. This situation is rare, however, among modern operating systems. </para> <para> - When <productname>PostgreSQL</> exceeds one of the various hard - <acronym>IPC</> limits, the server will refuse to start and + Upon starting the server, <productname>PostgreSQL</> normally allocates + a very small amount of System V shared memory, as well as a much larger + amount of POSIX (<function>mmap</>) shared memory. + In addition a significant number of semaphores, which can be either + System V or POSIX style, are created at server startup. Currently, + POSIX semaphores are used on Linux and FreeBSD systems while other + platforms use System V semaphores. + </para> + + <note> + <para> + Prior to <productname>PostgreSQL</> 9.3, only System V shared memory + was used, so the amount of System V shared memory required to start the + server was much larger. If you are running an older version of the + server, please consult the documentation for your server version. + </para> + </note> + + <para> + System V <acronym>IPC</> features are typically constrained by + system-wide allocation limits. + When <productname>PostgreSQL</> exceeds one of these limits, + the server will refuse to start and should leave an instructive error message describing the problem and what to do about it. (See also <xref linkend="server-start-failures">.) The relevant kernel @@ -1202,15 +1222,6 @@ psql: could not connect to server: No such file or directory them, however, vary. Suggestions for some platforms are given below. </para> - <note> - <para> - Prior to <productname>PostgreSQL</> 9.3, the amount of System V shared - memory required to start the server was much larger. If you are running - an older version of the server, please consult the documentation for - your server version. - </para> - </note> - <table id="sysvipc-parameters"> <title><systemitem class="osname">System V</> <acronym>IPC</> Parameters</title> @@ -1219,7 +1230,7 @@ psql: could not connect to server: No such file or directory <row> <entry>Name</> <entry>Description</> - <entry>Reasonable values</> + <entry>Values needed to run one <productname>PostgreSQL</> instance</> </row> </thead> @@ -1227,7 +1238,7 @@ psql: could not connect to server: No such file or directory <row> <entry><varname>SHMMAX</></> <entry>Maximum size of shared memory segment (bytes)</> - <entry>at least 1kB (more if running many copies of the server)</entry> + <entry>at least 1kB, but the default is usually much higher</entry> </row> <row> @@ -1239,7 +1250,9 @@ psql: could not connect to server: No such file or directory <row> <entry><varname>SHMALL</></> <entry>Total amount of shared memory available (bytes or pages)</> - <entry>if bytes, same as <varname>SHMMAX</varname>; if pages, <literal>ceil(SHMMAX/PAGE_SIZE)</literal></> + <entry>same as <varname>SHMMAX</varname> if bytes, + or <literal>ceil(SHMMAX/PAGE_SIZE)</literal> if pages, + plus room for other applications</> </row> <row> @@ -1257,7 +1270,7 @@ psql: could not connect to server: No such file or directory <row> <entry><varname>SEMMNI</></> <entry>Maximum number of semaphore identifiers (i.e., sets)</> - <entry>at least <literal>ceil((max_connections + autovacuum_max_workers + max_worker_processes + 5) / 16)</literal></> + <entry>at least <literal>ceil((max_connections + autovacuum_max_workers + max_worker_processes + 5) / 16)</literal> plus room for other applications</> </row> <row> @@ -1293,9 +1306,8 @@ psql: could not connect to server: No such file or directory (typically 48 bytes, on 64-bit platforms) for each copy of the server. On most modern operating systems, this amount can easily be allocated. However, if you are running many copies of the server, or if other - applications are also using System V shared memory, it may be necessary - to increase <varname>SHMMAX</>, the maximum size in bytes of a shared - memory segment, or <varname>SHMALL</>, the total amount of System V shared + applications are also using System V shared memory, it may be necessary to + increase <varname>SHMALL</>, which is the total amount of System V shared memory system-wide. Note that <varname>SHMALL</> is measured in pages rather than bytes on many systems. </para> @@ -1310,6 +1322,7 @@ psql: could not connect to server: No such file or directory </para> <para> + When using System V semaphores, <productname>PostgreSQL</> uses one semaphore per allowed connection (<xref linkend="guc-max-connections">), allowed autovacuum worker process (<xref linkend="guc-autovacuum-max-workers">) and allowed background @@ -1347,15 +1360,19 @@ psql: could not connect to server: No such file or directory </para> <para> - The <varname>SEMMSL</> parameter, which determines how many - semaphores can be in a set, must be at least 17 for + Various other settings related to <quote>semaphore undo</>, such as + <varname>SEMMNU</> and <varname>SEMUME</>, do not affect <productname>PostgreSQL</>. </para> <para> - Various other settings related to <quote>semaphore undo</>, such as - <varname>SEMMNU</> and <varname>SEMUME</>, do not affect - <productname>PostgreSQL</>. + When using POSIX semaphores, the number of semaphores needed is the + same as for System V, that is one semaphore per allowed connection + (<xref linkend="guc-max-connections">), allowed autovacuum worker process + (<xref linkend="guc-autovacuum-max-workers">) and allowed background + process (<xref linkend="guc-max-worker-processes">). + On the platforms where this option is preferred, there is no specific + kernel limit on the number of POSIX semaphores. </para> @@ -1574,12 +1591,12 @@ option SEMMAP=256 <varlistentry> - <term><systemitem class="osname">OS X</> - <indexterm><primary>OS X</><secondary>IPC configuration</></> + <term><systemitem class="osname">macOS</> + <indexterm><primary>macOS</><secondary>IPC configuration</></> </term> <listitem> <para> - The recommended method for configuring shared memory in OS X + The recommended method for configuring shared memory in macOS is to create a file named <filename>/etc/sysctl.conf</>, containing variable assignments such as: <programlisting> @@ -1589,13 +1606,13 @@ kern.sysv.shmmni=32 kern.sysv.shmseg=8 kern.sysv.shmall=1024 </programlisting> - Note that in some OS X versions, + Note that in some macOS versions, <emphasis>all five</> shared-memory parameters must be set in <filename>/etc/sysctl.conf</>, else the values will be ignored. </para> <para> - Beware that recent releases of OS X ignore attempts to set + Beware that recent releases of macOS ignore attempts to set <varname>SHMMAX</> to a value that isn't an exact multiple of 4096. </para> @@ -1604,7 +1621,7 @@ kern.sysv.shmall=1024 </para> <para> - In older OS X versions, you will need to reboot to have changes in the + In older macOS versions, you will need to reboot to have changes in the shared memory parameters take effect. As of 10.5 it is possible to change all but <varname>SHMMNI</> on the fly, using <application>sysctl</>. But it's still best to set up your preferred @@ -1613,7 +1630,7 @@ kern.sysv.shmall=1024 </para> <para> - The file <filename>/etc/sysctl.conf</> is only honored in OS X + The file <filename>/etc/sysctl.conf</> is only honored in macOS 10.3.9 and later. If you are running a previous 10.3.x release, you must edit the file <filename>/etc/rc</> and change the values in the following commands: @@ -1625,12 +1642,12 @@ sysctl -w kern.sysv.shmseg sysctl -w kern.sysv.shmall </programlisting> Note that - <filename>/etc/rc</> is usually overwritten by OS X system updates, + <filename>/etc/rc</> is usually overwritten by macOS system updates, so you should expect to have to redo these edits after each update. </para> <para> - In OS X 10.2 and earlier, instead edit these commands in the file + In macOS 10.2 and earlier, instead edit these commands in the file <filename>/System/Library/StartupItems/SystemTuning/SystemTuning</>. </para> </listitem> @@ -1638,34 +1655,6 @@ sysctl -w kern.sysv.shmall <varlistentry> - <term><systemitem class="osname">SCO OpenServer</> - <indexterm><primary>SCO OpenServer</><secondary>IPC configuration</></> - </term> - <listitem> - <para> - In the default configuration, only 512 kB of shared memory per - segment is allowed. To increase the setting, first change to the - directory <filename>/etc/conf/cf.d</>. To display the current value of - <varname>SHMMAX</>, run: -<programlisting> -./configure -y SHMMAX -</programlisting> - To set a new value for <varname>SHMMAX</>, run: -<programlisting> -./configure SHMMAX=<replaceable>value</> -</programlisting> - where <replaceable>value</> is the new value you want to use - (in bytes). After setting <varname>SHMMAX</>, rebuild the kernel: -<programlisting> -./link_unix -</programlisting> - and reboot. - </para> - </listitem> - </varlistentry> - - - <varlistentry> <term><systemitem class="osname">Solaris</> 2.6 to 2.9 (Solaris 6 to Solaris 9) <indexterm><primary>Solaris</><secondary>IPC configuration</></> @@ -1740,38 +1729,87 @@ project.max-msg-ids=(priv,4096,deny) </listitem> </varlistentry> + </variablelist> + + </sect2> - <varlistentry> - <term><systemitem class="osname">UnixWare</> - <indexterm><primary>UnixWare</><secondary>IPC configuration</></> - </term> - <listitem> - <para> - On <productname>UnixWare</> 7, the maximum size for shared - memory segments is 512 kB in the default configuration. - To display the current value of <varname>SHMMAX</>, run: -<programlisting> -/etc/conf/bin/idtune -g SHMMAX -</programlisting> - which displays the current, default, minimum, and maximum - values. To set a new value for <varname>SHMMAX</>, - run: -<programlisting> -/etc/conf/bin/idtune SHMMAX <replaceable>value</> -</programlisting> - where <replaceable>value</> is the new value you want to use - (in bytes). After setting <varname>SHMMAX</>, rebuild the - kernel: + <sect2 id="systemd-removeipc"> + <title>systemd RemoveIPC</title> + + <indexterm> + <primary>systemd</primary> + <secondary>RemoveIPC</secondary> + </indexterm> + + <para> + If <productname>systemd</productname> is in use, some care must be taken + that IPC resources (shared memory and semaphores) are not prematurely + removed by the operating system. This is especially of concern when + installing PostgreSQL from source. Users of distribution packages of + PostgreSQL are less likely to be affected, as + the <literal>postgres</literal> user is then normally created as a system + user. + </para> + + <para> + The setting <literal>RemoveIPC</literal> + in <filename>logind.conf</filename> controls whether IPC objects are + removed when a user fully logs out. System users are exempt. This + setting defaults to on in stock <productname>systemd</productname>, but + some operating system distributions default it to off. + </para> + + <para> + A typical observed effect when this setting is on is that the semaphore + objects used by a PostgreSQL server are removed at apparently random + times, leading to the server crashing with log messages like +<screen> +LOG: semctl(1234567890, 0, IPC_RMID, ...) failed: Invalid argument +</screen> + Different types of IPC objects (shared memory vs. semaphores, System V + vs. POSIX) are treated slightly differently + by <productname>systemd</productname>, so one might observe that some IPC + resources are not removed in the same way as others. But it is not + advisable to rely on these subtle differences. + </para> + + <para> + A <quote>user logging out</quote> might happen as part of a maintenance + job or manually when an administrator logs in as + the <literal>postgres</literal> user or something similar, so it is hard + to prevent in general. + </para> + + <para> + What is a <quote>system user</quote> is determined + at <productname>systemd</productname> compile time from + the <symbol>SYS_UID_MAX</symbol> setting + in <filename>/etc/login.defs</filename>. + </para> + + <para> + Packaging and deployment scripts should be careful to create + the <literal>postgres</literal> user as a system user by + using <literal>useradd -r</literal>, <literal>adduser --system</literal>, + or equivalent. + </para> + + <para> + Alternatively, if the user account was created incorrectly or cannot be + changed, it is recommended to set <programlisting> -/etc/conf/bin/idbuild -B +RemoveIPC=no </programlisting> - and reboot. - </para> - </listitem> - </varlistentry> - - </variablelist> + in <filename>/etc/systemd/logind.conf</filename> or another appropriate + configuration file. + </para> + <caution> + <para> + At least one of these two things has to be ensured, or the PostgreSQL + server will be very unreliable. + </para> + </caution> </sect2> <sect2> @@ -1990,53 +2028,67 @@ export PG_OOM_ADJUST_VALUE=0 </sect2> <sect2 id="linux-huge-pages"> - <title>Linux huge pages</title> + <title>Linux Huge Pages</title> <para> Using huge pages reduces overhead when using large contiguous chunks of - memory, like <productname>PostgreSQL</productname> does. To enable this + memory, as <productname>PostgreSQL</productname> does, particularly when + using large values of <xref linkend="guc-shared-buffers">. To use this feature in <productname>PostgreSQL</productname> you need a kernel with <varname>CONFIG_HUGETLBFS=y</varname> and - <varname>CONFIG_HUGETLB_PAGE=y</varname>. You also have to tune the system - setting <varname>vm.nr_hugepages</varname>. To estimate the number of - necessary huge pages start <productname>PostgreSQL</productname> without - huge pages enabled and check the <varname>VmPeak</varname> value from the - proc file system: + <varname>CONFIG_HUGETLB_PAGE=y</varname>. You will also have to adjust + the kernel setting <varname>vm.nr_hugepages</varname>. To estimate the + number of huge pages needed, start <productname>PostgreSQL</productname> + without huge pages enabled and check the + postmaster's <varname>VmPeak</varname> value, as well as the system's + huge page size, using the <filename>/proc</> file system. This might + look like: <programlisting> -$ <userinput>head -1 /path/to/data/directory/postmaster.pid</userinput> +$ <userinput>head -1 $PGDATA/postmaster.pid</userinput> 4170 $ <userinput>grep ^VmPeak /proc/4170/status</userinput> VmPeak: 6490428 kB +$ <userinput>grep ^Hugepagesize /proc/meminfo</userinput> +Hugepagesize: 2048 kB </programlisting> - <literal>6490428</literal> / <literal>2048</literal> - (<varname>PAGE_SIZE</varname> is <literal>2MB</literal> in this case) are - roughly <literal>3169.154</literal> huge pages, so you will need at - least <literal>3170</literal> huge pages: + <literal>6490428</literal> / <literal>2048</literal> gives approximately + <literal>3169.154</literal>, so in this example we need at + least <literal>3170</literal> huge pages, which we can set with: <programlisting> $ <userinput>sysctl -w vm.nr_hugepages=3170</userinput> </programlisting> + A larger setting would be appropriate if other programs on the machine + also need huge pages. Don't forget to add this setting + to <filename>/etc/sysctl.conf</filename> so that it will be reapplied + after reboots. + </para> + + <para> Sometimes the kernel is not able to allocate the desired number of huge - pages, so it might be necessary to repeat that command or to reboot. Don't - forget to add an entry to <filename>/etc/sysctl.conf</filename> to persist - this setting through reboots. + pages immediately, so it might be necessary to repeat the command or to + reboot. (Immediately after a reboot, most of the machine's memory + should be available to convert into huge pages.) To verify the huge + page allocation situation, use: +<programlisting> +$ <userinput>grep Huge /proc/meminfo</userinput> +</programlisting> </para> <para> - It is also necessary to give the database server operating system + It may also be necessary to give the database server's operating system user permission to use huge pages by setting - <varname>vm.hugetlb_shm_group</> via <application>sysctl</>, and - permission to lock memory with <command>ulimit -l</>. + <varname>vm.hugetlb_shm_group</> via <application>sysctl</>, and/or + give permission to lock memory with <command>ulimit -l</>. </para> <para> The default behavior for huge pages in <productname>PostgreSQL</productname> is to use them when possible and - to fallback to normal pages when failing. To enforce the use of huge - pages, you can set - <link linkend="guc-huge-pages"><varname>huge_pages</varname></link> - to <literal>on</literal>. Note that in this case - <productname>PostgreSQL</productname> will fail to start if not enough huge - pages are available. + to fall back to normal pages when failing. To enforce the use of huge + pages, you can set <xref linkend="guc-huge-pages"> + to <literal>on</literal> in <filename>postgresql.conf</>. + Note that with this setting <productname>PostgreSQL</> will fail to + start if not enough huge pages are available. </para> <para> @@ -2211,17 +2263,26 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput </para> <para> - <productname>PostgreSQL</> major versions are represented by the - first two digit groups of the version number, e.g., 8.4. - <productname>PostgreSQL</> minor versions are represented by the - third group of version digits, e.g., 8.4.2 is the second minor - release of 8.4. Minor releases never change the internal storage - format and are always compatible with earlier and later minor - releases of the same major version number, e.g., 8.4.2 is compatible - with 8.4, 8.4.1 and 8.4.6. To update between compatible versions, - you simply replace the executables while the server is down and - restart the server. The data directory remains unchanged — - minor upgrades are that simple. + Current <productname>PostgreSQL</productname> version numbers consist of a + major and a minor version number. For example, in the version number 10.1, + the 10 is the major version number and the 1 is the minor version number, + meaning this would be the first minor release of the major release 10. For + releases before <productname>PostgreSQL</productname> version 10.0, version + numbers consist of three numbers, for example, 9.5.3. In those cases, the + major version consists of the first two digit groups of the version number, + e.g., 9.5, and the minor version is the third number, e.g., 3, meaning this + would be the third minor release of the major release 9.5. + </para> + + <para> + Minor releases never change the internal storage format and are always + compatible with earlier and later minor releases of the same major version + number. For example, version 10.1 is compatible with version 10.0 and + version 10.6. Similarly, for example, 9.5.3 is compatible with 9.5.0, + 9.5.1, and 9.5.6. To update between compatible versions, you simply + replace the executables while the server is down and restart the server. + The data directory remains unchanged — minor upgrades are that + simple. </para> <para> @@ -2532,7 +2593,7 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 </para> <para> - The simplest way to prevent spoofing for <literal>local</> + One way to prevent spoofing of <literal>local</> connections is to use a Unix domain socket directory (<xref linkend="guc-unix-socket-directories">) that has write permission only for a trusted local user. This prevents a malicious user from creating @@ -2545,6 +2606,13 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 </para> <para> + Another option for <literal>local</> connections is for clients to use + <link linkend="libpq-connect-requirepeer"><literal>requirepeer</></> + to specify the required owner of the server process connected to + the socket. + </para> + + <para> To prevent spoofing on TCP connections, the best solution is to use SSL certificates and make sure that clients check the server's certificate. To do that, the server @@ -2792,6 +2860,10 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 If the private key is protected with a passphrase, the server will prompt for the passphrase and will not start until it has been entered. + Using a passphrase also disables the ability to change the server's SSL + configuration without a server restart. + Furthermore, passphrase-protected private keys cannot be used at all + on Windows. </para> <para> @@ -2915,11 +2987,20 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 </table> <para> - The files <filename>server.key</>, <filename>server.crt</>, - <filename>root.crt</filename>, and <filename>root.crl</filename> - (or their configured alternative names) - are only examined during server start; so you must restart - the server for changes in them to take effect. + The server reads these files at server start and whenever the server + configuration is reloaded. On <systemitem class="osname">Windows</> + systems, they are also re-read whenever a new backend process is spawned + for a new client connection. + </para> + + <para> + If an error in these files is detected at server start, the server will + refuse to start. But if an error is detected during a configuration + reload, the files are ignored and the old SSL configuration continues to + be used. On <systemitem class="osname">Windows</> systems, if an error in + these files is detected at backend start, that backend will be unable to + establish an SSL connection. In all these cases, the error condition is + reported in the server log. </para> </sect2> @@ -2927,28 +3008,14 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433 <title>Creating a Self-signed Certificate</title> <para> - To create a quick self-signed certificate for the server, use the - following <productname>OpenSSL</productname> command: -<programlisting> -openssl req -new -text -out server.req -</programlisting> - Fill out the information that <application>openssl</> asks for. Make sure - you enter the local host name as <quote>Common Name</>; the challenge - password can be left blank. The program will generate a key that is - passphrase protected; it will not accept a passphrase that is less - than four characters long. To remove the passphrase (as you must if - you want automatic start-up of the server), run the commands: -<programlisting> -openssl rsa -in privkey.pem -out server.key -rm privkey.pem -</programlisting> - Enter the old passphrase to unlock the existing key. Now do: + To create a quick self-signed certificate for the server, valid for 365 + days, use the following <productname>OpenSSL</productname> command, + replacing <replaceable>yourdomain.com</> with the server's host name: <programlisting> -openssl req -x509 -in server.req -text -key server.key -out server.crt +openssl req -new -x509 -days 365 -nodes -text -out server.crt \ + -keyout server.key -subj "/CN=<replaceable>yourdomain.com</>" </programlisting> - to turn the certificate into a self-signed certificate and to copy - the key and certificate to where the server will look for them. - Finally do: + Then do: <programlisting> chmod og-rwx server.key </programlisting> diff --git a/doc/src/sgml/sepgsql.sgml b/doc/src/sgml/sepgsql.sgml index 6f80933abd..0b611eeeca 100644 --- a/doc/src/sgml/sepgsql.sgml +++ b/doc/src/sgml/sepgsql.sgml @@ -753,7 +753,7 @@ ERROR: SELinux: security policy violation <title>External Resources</title> <variablelist> <varlistentry> - <term><ulink url="http://wiki.postgresql.org/wiki/SEPostgreSQL">SE-PostgreSQL Introduction</ulink></term> + <term><ulink url="https://wiki.postgresql.org/wiki/SEPostgreSQL">SE-PostgreSQL Introduction</ulink></term> <listitem> <para> This wiki page provides a brief overview, security design, architecture, diff --git a/doc/src/sgml/sourcerepo.sgml b/doc/src/sgml/sourcerepo.sgml index 08cafe129b..59b996edc9 100644 --- a/doc/src/sgml/sourcerepo.sgml +++ b/doc/src/sgml/sourcerepo.sgml @@ -12,7 +12,7 @@ <para> Our wiki, <ulink - url="http://wiki.postgresql.org/wiki/Working_with_Git"></ulink>, + url="https://wiki.postgresql.org/wiki/Working_with_Git"></ulink>, has some discussion on working with Git. </para> @@ -64,10 +64,10 @@ git clone git://git.postgresql.org/git/postgres-xl.git <para> The Git mirror can also be reached via the HTTP protocol, if for example a firewall is blocking access to the Git protocol. Just change the URL - prefix to <literal>http</>, as in: + prefix to <literal>https</>, as in: <programlisting> -git clone http://git.postgresql.org/git/postgres-xl.git +git clone https://git.postgresql.org/git/postgres-xl.git </programlisting> The HTTP protocol is less efficient than the Git protocol, so it will be diff --git a/doc/src/sgml/sources.sgml b/doc/src/sgml/sources.sgml index d132ee4a2e..877fcedbb3 100644 --- a/doc/src/sgml/sources.sgml +++ b/doc/src/sgml/sources.sgml @@ -898,7 +898,7 @@ BETTER: unrecognized node type: 42 expressions of various types need to be passed to the macro. </para> <para> - When the definition an inline function references symbols + When the definition of an inline function references symbols (i.e. variables, functions) that are only available as part of the backend, the function may not be visible when included from frontend code. diff --git a/doc/src/sgml/spgist.sgml b/doc/src/sgml/spgist.sgml index f40c790612..cd4a8d07c4 100644 --- a/doc/src/sgml/spgist.sgml +++ b/doc/src/sgml/spgist.sgml @@ -114,7 +114,7 @@ </row> <row> <entry><literal>box_ops</></entry> - <entry>box</entry> + <entry><type>box</></entry> <entry> <literal><<</> <literal>&<</> @@ -145,6 +145,23 @@ <literal>~>~</> </entry> </row> + <row> + <entry><literal>inet_ops</></entry> + <entry><type>inet</>, <type>cidr</></entry> + <entry> + <literal>&&</> + <literal>>></> + <literal>>>=</> + <literal>></> + <literal>>=</> + <literal><></> + <literal><<</> + <literal><<=</> + <literal><</> + <literal><=</> + <literal>=</> + </entry> + </row> </tbody> </tgroup> </table> @@ -183,11 +200,14 @@ Inner tuples are more complex, since they are branching points in the search tree. Each inner tuple contains a set of one or more <firstterm>nodes</>, which represent groups of similar leaf values. - A node contains a downlink that leads to either another, lower-level inner - tuple, or a short list of leaf tuples that all lie on the same index page. - Each node has a <firstterm>label</> that describes it; for example, + A node contains a downlink that leads either to another, lower-level inner + tuple, or to a short list of leaf tuples that all lie on the same index page. + Each node normally has a <firstterm>label</> that describes it; for example, in a radix tree the node label could be the next character of the string - value. Optionally, an inner tuple can have a <firstterm>prefix</> value + value. (Alternatively, an operator class can omit the node labels, if it + works with a fixed set of nodes for all inner tuples; + see <xref linkend="spgist-null-labels">.) + Optionally, an inner tuple can have a <firstterm>prefix</> value that describes all its members. In a radix tree this could be the common prefix of the represented strings. The prefix value is not necessarily really a prefix, but can be any data needed by the operator class; @@ -202,7 +222,8 @@ tuple, so the <acronym>SP-GiST</acronym> core provides the possibility for operator classes to manage level counting while descending the tree. There is also support for incrementally reconstructing the represented - value when that is needed. + value when that is needed, and for passing down additional data (called + <firstterm>traverse values</>) during a tree descent. </para> <note> @@ -343,10 +364,13 @@ typedef struct spgChooseOut } addNode; struct /* results for spgSplitTuple */ { - /* Info to form new inner tuple with one node */ + /* Info to form new upper-level inner tuple with one child tuple */ bool prefixHasPrefix; /* tuple should have a prefix? */ Datum prefixPrefixDatum; /* if so, its value */ - Datum nodeLabel; /* node's label */ + int prefixNNodes; /* number of nodes */ + Datum *prefixNodeLabels; /* their labels (or NULL for + * no labels) */ + int childNodeN; /* which node gets child tuple */ /* Info to form new lower-level inner tuple with all old nodes */ bool postfixHasPrefix; /* tuple should have a prefix? */ @@ -416,29 +440,33 @@ typedef struct spgChooseOut set <structfield>resultType</> to <literal>spgSplitTuple</>. This action moves all the existing nodes into a new lower-level inner tuple, and replaces the existing inner tuple with a tuple - having a single node that links to the new lower-level inner tuple. + having a single downlink pointing to the new lower-level inner tuple. Set <structfield>prefixHasPrefix</> to indicate whether the new upper tuple should have a prefix, and if so set <structfield>prefixPrefixDatum</> to the prefix value. This new prefix value must be sufficiently less restrictive than the original - to accept the new value to be indexed, and it should be no longer - than the original prefix. - Set <structfield>nodeLabel</> to the label to be used for the - node that will point to the new lower-level inner tuple. + to accept the new value to be indexed. + Set <structfield>prefixNNodes</> to the number of nodes needed in the + new tuple, and set <structfield>prefixNodeLabels</> to a palloc'd array + holding their labels, or to NULL if node labels are not required. + Note that the total size of the new upper tuple must be no more + than the total size of the tuple it is replacing; this constrains + the lengths of the new prefix and new labels. + Set <structfield>childNodeN</> to the index (from zero) of the node + that will downlink to the new lower-level inner tuple. Set <structfield>postfixHasPrefix</> to indicate whether the new lower-level inner tuple should have a prefix, and if so set <structfield>postfixPrefixDatum</> to the prefix value. The - combination of these two prefixes and the additional label must - have the same meaning as the original prefix, because there is - no opportunity to alter the node labels that are moved to the new - lower-level tuple, nor to change any child index entries. + combination of these two prefixes and the downlink node's label + (if any) must have the same meaning as the original prefix, because + there is no opportunity to alter the node labels that are moved to + the new lower-level tuple, nor to change any child index entries. After the node has been split, the <function>choose</function> function will be called again with the replacement inner tuple. - That call will usually result in an <literal>spgAddNode</> result, - since presumably the node label added in the split step will not - match the new value; so after that, there will be a third call - that finally returns <literal>spgMatchNode</> and allows the - insertion to descend to the leaf level. + That call may return an <literal>spgAddNode</> result, if no suitable + node was created by the <literal>spgSplitTuple</> action. Eventually + <function>choose</function> must return <literal>spgMatchNode</> to + allow the insertion to descend to the next level. </para> </listitem> </varlistentry> @@ -492,9 +520,8 @@ typedef struct spgPickSplitOut <structfield>prefixDatum</> to the prefix value. Set <structfield>nNodes</> to indicate the number of nodes that the new inner tuple will contain, and - set <structfield>nodeLabels</> to an array of their label values. - (If the nodes do not require labels, set <structfield>nodeLabels</> - to NULL; see <xref linkend="spgist-null-labels"> for details.) + set <structfield>nodeLabels</> to an array of their label values, + or to NULL if node labels are not required. Set <structfield>mapTuplesToNodes</> to an array that gives the index (from zero) of the node that each leaf tuple should be assigned to. Set <structfield>leafTupleDatums</> to an array of the values to @@ -561,7 +588,7 @@ typedef struct spgInnerConsistentIn Datum reconstructedValue; /* value reconstructed at parent */ void *traversalValue; /* opclass-specific traverse value */ - MemoryContext traversalMemoryContext; + MemoryContext traversalMemoryContext; /* put new traverse values here */ int level; /* current level (counting from zero) */ bool returnData; /* original data must be returned? */ @@ -580,7 +607,6 @@ typedef struct spgInnerConsistentOut int *levelAdds; /* increment level by this much for each */ Datum *reconstructedValues; /* associated reconstructed values */ void **traversalValues; /* opclass-specific traverse values */ - } spgInnerConsistentOut; </programlisting> @@ -599,6 +625,11 @@ typedef struct spgInnerConsistentOut parent tuple; it is <literal>(Datum) 0</> at the root level or if the <function>inner_consistent</> function did not provide a value at the parent level. + <structfield>traversalValue</> is a pointer to any traverse data + passed down from the previous call of <function>inner_consistent</> + on the parent index tuple, or NULL at the root level. + <structfield>traversalMemoryContext</> is the memory context in which + to store output traverse values (see below). <structfield>level</> is the current inner tuple's level, starting at zero for the root level. <structfield>returnData</> is <literal>true</> if reconstructed data is @@ -615,9 +646,6 @@ typedef struct spgInnerConsistentOut inner tuple, and <structfield>nodeLabels</> is an array of their label values, or NULL if the nodes do not have labels. - <structfield>traversalValue</> is a pointer to data that - <function>inner_consistent</> gets when called on child nodes from an - outer call of <function>inner_consistent</> on parent nodes. </para> <para> @@ -633,17 +661,20 @@ typedef struct spgInnerConsistentOut <structfield>reconstructedValues</> to an array of the values reconstructed for each child node to be visited; otherwise, leave <structfield>reconstructedValues</> as NULL. + If it is desired to pass down additional out-of-band information + (<quote>traverse values</>) to lower levels of the tree search, + set <structfield>traversalValues</> to an array of the appropriate + traverse values, one for each child node to be visited; otherwise, + leave <structfield>traversalValues</> as NULL. Note that the <function>inner_consistent</> function is responsible for palloc'ing the - <structfield>nodeNumbers</>, <structfield>levelAdds</> and - <structfield>reconstructedValues</> arrays. - Sometimes accumulating some information is needed, while - descending from parent to child node was happened. In this case - <structfield>traversalValues</> array keeps pointers to - specific data you need to accumulate for every child node. - Memory for <structfield>traversalValues</> should be allocated in - the default context, but each element of it should be allocated in - <structfield>traversalMemoryContext</>. + <structfield>nodeNumbers</>, <structfield>levelAdds</>, + <structfield>reconstructedValues</>, and + <structfield>traversalValues</> arrays in the current memory context. + However, any output traverse values pointed to by + the <structfield>traversalValues</> array should be allocated + in <structfield>traversalMemoryContext</>. + Each traverse value must be a single palloc'd chunk. </para> </listitem> </varlistentry> @@ -670,8 +701,8 @@ typedef struct spgLeafConsistentIn ScanKey scankeys; /* array of operators and comparison values */ int nkeys; /* length of array */ - void *traversalValue; /* opclass-specific traverse value */ Datum reconstructedValue; /* value reconstructed at parent */ + void *traversalValue; /* opclass-specific traverse value */ int level; /* current level (counting from zero) */ bool returnData; /* original data must be returned? */ @@ -700,6 +731,9 @@ typedef struct spgLeafConsistentOut parent tuple; it is <literal>(Datum) 0</> at the root level or if the <function>inner_consistent</> function did not provide a value at the parent level. + <structfield>traversalValue</> is a pointer to any traverse data + passed down from the previous call of <function>inner_consistent</> + on the parent index tuple, or NULL at the root level. <structfield>level</> is the current leaf tuple's level, starting at zero for the root level. <structfield>returnData</> is <literal>true</> if reconstructed data is @@ -797,7 +831,10 @@ typedef struct spgLeafConsistentOut point. In such a case the code typically works with the nodes by number, and there is no need for explicit node labels. To suppress node labels (and thereby save some space), the <function>picksplit</> - function can return NULL for the <structfield>nodeLabels</> array. + function can return NULL for the <structfield>nodeLabels</> array, + and likewise the <function>choose</> function can return NULL for + the <structfield>prefixNodeLabels</> array during + a <literal>spgSplitTuple</> action. This will in turn result in <structfield>nodeLabels</> being NULL during subsequent calls to <function>choose</> and <function>inner_consistent</>. In principle, node labels could be used for some inner tuples and omitted @@ -807,10 +844,7 @@ typedef struct spgLeafConsistentOut <para> When working with an inner tuple having unlabeled nodes, it is an error for <function>choose</> to return <literal>spgAddNode</>, since the set - of nodes is supposed to be fixed in such cases. Also, there is no - provision for generating an unlabeled node in <literal>spgSplitTuple</> - actions, since it is expected that an <literal>spgAddNode</> action will - be needed as well. + of nodes is supposed to be fixed in such cases. </para> </sect2> @@ -859,11 +893,10 @@ typedef struct spgLeafConsistentOut <para> The <productname>PostgreSQL</productname> source distribution includes - several examples of index operator classes for - <acronym>SP-GiST</acronym>. The core system currently provides radix - trees over text columns and two types of trees over points: quad-tree and - k-d tree. Look into <filename>src/backend/access/spgist/</> to see the - code. + several examples of index operator classes for <acronym>SP-GiST</acronym>, + as described in <xref linkend="spgist-builtin-opclasses-table">. Look + into <filename>src/backend/access/spgist/</> + and <filename>src/backend/utils/adt/</> to see the code. </para> </sect1> diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml index 9ae7126ae7..86be87c0fd 100644 --- a/doc/src/sgml/spi.sgml +++ b/doc/src/sgml/spi.sgml @@ -90,21 +90,6 @@ int SPI_connect(void) function if you want to execute commands through SPI. Some utility SPI functions can be called from unconnected procedures. </para> - - <para> - If your procedure is already connected, - <function>SPI_connect</function> will return the error code - <returnvalue>SPI_ERROR_CONNECT</returnvalue>. This could happen if - a procedure that has called <function>SPI_connect</function> - directly calls another procedure that calls - <function>SPI_connect</function>. While recursive calls to the - <acronym>SPI</acronym> manager are permitted when an SQL command - called through SPI invokes another function that uses - <acronym>SPI</acronym>, directly nested calls to - <function>SPI_connect</function> and - <function>SPI_finish</function> are forbidden. - (But see <function>SPI_push</function> and <function>SPI_pop</function>.) - </para> </refsect1> <refsect1> @@ -164,13 +149,6 @@ int SPI_finish(void) abort the transaction via <literal>elog(ERROR)</literal>. In that case SPI will clean itself up automatically. </para> - - <para> - If <function>SPI_finish</function> is called without having a valid - connection, it will return <symbol>SPI_ERROR_UNCONNECTED</symbol>. - There is no fundamental problem with this; it means that the SPI - manager has nothing to do. - </para> </refsect1> <refsect1> @@ -200,86 +178,6 @@ int SPI_finish(void) <!-- *********************************************** --> -<refentry id="spi-spi-push"> - <indexterm><primary>SPI_push</primary></indexterm> - - <refmeta> - <refentrytitle>SPI_push</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>SPI_push</refname> - <refpurpose>push SPI stack to allow recursive SPI usage</refpurpose> - </refnamediv> - - <refsynopsisdiv> -<synopsis> -void SPI_push(void) -</synopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para> - <function>SPI_push</function> should be called before executing another - procedure that might itself wish to use SPI. - After <function>SPI_push</function>, SPI is no longer in a - <quote>connected</> state, and SPI function calls will be rejected unless - a fresh <function>SPI_connect</function> is done. This ensures a clean - separation between your procedure's SPI state and that of another procedure - you call. After the other procedure returns, call - <function>SPI_pop</function> to restore access to your own SPI state. - </para> - - <para> - Note that <function>SPI_execute</function> and related functions - automatically do the equivalent of <function>SPI_push</function> before - passing control back to the SQL execution engine, so it is not necessary - for you to worry about this when using those functions. - Only when you are directly calling arbitrary code that might contain - <function>SPI_connect</function> calls do you need to issue - <function>SPI_push</function> and <function>SPI_pop</function>. - </para> - </refsect1> - -</refentry> - -<!-- *********************************************** --> - -<refentry id="spi-spi-pop"> - <indexterm><primary>SPI_pop</primary></indexterm> - - <refmeta> - <refentrytitle>SPI_pop</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>SPI_pop</refname> - <refpurpose>pop SPI stack to return from recursive SPI usage</refpurpose> - </refnamediv> - - <refsynopsisdiv> -<synopsis> -void SPI_pop(void) -</synopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para> - <function>SPI_pop</function> pops the previous environment from the - SPI call stack. See <function>SPI_push</function>. - </para> - </refsect1> - -</refentry> - -<!-- *********************************************** --> - <refentry id="spi-spi-execute"> <indexterm><primary>SPI_execute</primary></indexterm> @@ -2741,6 +2639,335 @@ SPIPlanPtr SPI_saveplan(SPIPlanPtr <parameter>plan</parameter>) </refsect1> </refentry> +<!-- *********************************************** --> + +<refentry id="spi-spi-register-relation"> + <indexterm><primary>SPI_register_relation</primary></indexterm> + + <indexterm> + <primary>ephemeral named relation</primary> + <secondary>registering with SPI</secondary> + </indexterm> + + <refmeta> + <refentrytitle>SPI_register_relation</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>SPI_register_relation</refname> + <refpurpose>make a ephemeral named relation available by name in SPI queries</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +int SPI_register_relation(EphemeralNamedRelation <parameter>enr</parameter>) +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <function>SPI_register_relation</function> makes an ephemeral named + relation, with associated information, available to queries planned and + executed through the current SPI connection. + </para> + </refsect1> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><literal>EphemeralNamedRelation <parameter>enr</parameter></literal></term> + <listitem> + <para> + the ephemeral named relation registry entry + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para> + If the execution of the command was successful then the following + (nonnegative) value will be returned: + + <variablelist> + <varlistentry> + <term><symbol>SPI_OK_REL_REGISTER</symbol></term> + <listitem> + <para> + if the relation has been successfully registered by name + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + On error, one of the following negative values is returned: + + <variablelist> + <varlistentry> + <term><symbol>SPI_ERROR_ARGUMENT</symbol></term> + <listitem> + <para> + if <parameter>enr</parameter> is <symbol>NULL</symbol> or its + <varname>name</varname> field is <symbol>NULL</symbol> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term> + <listitem> + <para> + if called from an unconnected procedure + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><symbol>SPI_ERROR_REL_DUPLICATE</symbol></term> + <listitem> + <para> + if the name specified in the <varname>name</varname> field of + <parameter>enr</parameter> is already registered for this connection + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> +</refentry> + +<!-- *********************************************** --> + +<refentry id="spi-spi-unregister-relation"> + <indexterm><primary>SPI_unregister_relation</primary></indexterm> + + <indexterm> + <primary>ephemeral named relation</primary> + <secondary>unregistering from SPI</secondary> + </indexterm> + + <refmeta> + <refentrytitle>SPI_unregister_relation</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>SPI_unregister_relation</refname> + <refpurpose>remove an ephemeral named relation from the registry</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +int SPI_unregister_relation(const char * <parameter>name</parameter>) +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <function>SPI_unregister_relation</function> removes an ephemeral named + relation from the registry for the current connection. + </para> + </refsect1> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><literal>const char * <parameter>name</parameter></literal></term> + <listitem> + <para> + the relation registry entry name + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para> + If the execution of the command was successful then the following + (nonnegative) value will be returned: + + <variablelist> + <varlistentry> + <term><symbol>SPI_OK_REL_UNREGISTER</symbol></term> + <listitem> + <para> + if the tuplestore has been successfully removed from the registry + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + On error, one of the following negative values is returned: + + <variablelist> + <varlistentry> + <term><symbol>SPI_ERROR_ARGUMENT</symbol></term> + <listitem> + <para> + if <parameter>name</parameter> is <symbol>NULL</symbol> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term> + <listitem> + <para> + if called from an unconnected procedure + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><symbol>SPI_ERROR_REL_NOT_FOUND</symbol></term> + <listitem> + <para> + if <parameter>name</parameter> is not found in the registry for the + current connection + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> +</refentry> + +<!-- *********************************************** --> + +<refentry id="spi-spi-register-trigger-data"> + <indexterm><primary>SPI_register_trigger_data</primary></indexterm> + + <indexterm> + <primary>ephemeral named relation</primary> + <secondary>registering with SPI</secondary> + </indexterm> + + <indexterm> + <primary>transition tables</primary> + <secondary>implementation in PLs</secondary> + </indexterm> + + <refmeta> + <refentrytitle>SPI_register_trigger_data</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>SPI_register_trigger_data</refname> + <refpurpose>make ephemeral trigger data available in SPI queries</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +int SPI_register_trigger_data(TriggerData *<parameter>tdata</parameter>) +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <function>SPI_register_trigger_data</function> makes any ephemeral + relations captured by a trigger available to queries planned and executed + through the current SPI connection. Currently, this means the transition + tables captured by an <literal>AFTER</literal> trigger defined with a + <literal>REFERENCING OLD/NEW TABLE AS</literal> ... clause. This function + should be called by a PL trigger handler function after connecting. + </para> + </refsect1> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><literal>TriggerData *<parameter>tdata</parameter></literal></term> + <listitem> + <para> + the <structname>TriggerData</structname> object passed to a trigger + handler function as <literal>fcinfo->context</literal> + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para> + If the execution of the command was successful then the following + (nonnegative) value will be returned: + + <variablelist> + <varlistentry> + <term><symbol>SPI_OK_TD_REGISTER</symbol></term> + <listitem> + <para> + if the captured trigger data (if any) has been successfully registered + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + On error, one of the following negative values is returned: + + <variablelist> + <varlistentry> + <term><symbol>SPI_ERROR_ARGUMENT</symbol></term> + <listitem> + <para> + if <parameter>tdata</parameter> is <symbol>NULL</symbol> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term> + <listitem> + <para> + if called from an unconnected procedure + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><symbol>SPI_ERROR_REL_DUPLICATE</symbol></term> + <listitem> + <para> + if the name of any trigger data transient relation is already + registered for this connection + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> +</refentry> + +<!-- *********************************************** --> + </sect1> <sect1 id="spi-interface-support"> @@ -2891,7 +3118,7 @@ int SPI_fnumber(TupleDesc <parameter>rowdesc</parameter>, const char * <paramete <title>Return Value</title> <para> - Column number (count starts at 1), or + Column number (count starts at 1 for user-defined columns), or <symbol>SPI_ERROR_NOATTRIBUTE</symbol> if the named column was not found. </para> @@ -3361,17 +3588,8 @@ char * SPI_getnspname(Relation <parameter>rel</parameter>) <quote>upper executor context</quote>, that is, the memory context that was current when <function>SPI_connect</function> was called, which is precisely the right context for a value returned from your - procedure. - </para> - - <para> - If <function>SPI_palloc</function> is called while the procedure is - not connected to SPI, then it acts the same as a normal - <function>palloc</function>. Before a procedure connects to the - SPI manager, the current memory context is the upper executor - context, so all allocations made by the procedure via - <function>palloc</function> or by SPI utility functions are made in - this context. + procedure. Several of the other utility procedures described in + this section also return objects created in the upper executor context. </para> <para> @@ -3379,24 +3597,14 @@ char * SPI_getnspname(Relation <parameter>rel</parameter>) context of the procedure, which is created by <function>SPI_connect</function>, is made the current context. All allocations made by <function>palloc</function>, - <function>repalloc</function>, or SPI utility functions (except for - <function>SPI_copytuple</function>, - <function>SPI_returntuple</function>, - <function>SPI_modifytuple</function>, and - <function>SPI_palloc</function>) are made in this context. When a + <function>repalloc</function>, or SPI utility functions (except as + described in this section) are made in this context. When a procedure disconnects from the SPI manager (via <function>SPI_finish</function>) the current context is restored to the upper executor context, and all allocations made in the procedure memory context are freed and cannot be used any more. </para> - <para> - All functions described in this section can be used by both - connected and unconnected procedures. In an unconnected procedure, - they act the same as the underlying ordinary server functions - (<function>palloc</>, etc.). - </para> - <!-- *********************************************** --> <refentry id="spi-spi-palloc"> @@ -3425,6 +3633,11 @@ void * SPI_palloc(Size <parameter>size</parameter>) <function>SPI_palloc</function> allocates memory in the upper executor context. </para> + + <para> + This function can only be used while connected to SPI. + Otherwise, it throws an error. + </para> </refsect1> <refsect1> @@ -3604,6 +3817,12 @@ HeapTuple SPI_copytuple(HeapTuple <parameter>row</parameter>) row from a trigger. In a function declared to return a composite type, use <function>SPI_returntuple</function> instead. </para> + + <para> + This function can only be used while connected to SPI. + Otherwise, it returns NULL and sets <varname>SPI_result</varname> to + <symbol>SPI_ERROR_UNCONNECTED</symbol>. + </para> </refsect1> <refsect1> @@ -3625,8 +3844,8 @@ HeapTuple SPI_copytuple(HeapTuple <parameter>row</parameter>) <title>Return Value</title> <para> - the copied row; <symbol>NULL</symbol> only if - <parameter>tuple</parameter> is <symbol>NULL</symbol> + the copied row, or <symbol>NULL</symbol> on error + (see <varname>SPI_result</varname> for an error indication) </para> </refsect1> </refentry> @@ -3663,6 +3882,12 @@ HeapTupleHeader SPI_returntuple(HeapTuple <parameter>row</parameter>, TupleDesc </para> <para> + This function can only be used while connected to SPI. + Otherwise, it returns NULL and sets <varname>SPI_result</varname> to + <symbol>SPI_ERROR_UNCONNECTED</symbol>. + </para> + + <para> Note that this should be used for functions that are declared to return composite types. It is not used for triggers; use <function>SPI_copytuple</> for returning a modified row in a trigger. @@ -3698,10 +3923,9 @@ HeapTupleHeader SPI_returntuple(HeapTuple <parameter>row</parameter>, TupleDesc <title>Return Value</title> <para> - <type>HeapTupleHeader</type> pointing to copied row; - <symbol>NULL</symbol> only if - <parameter>row</parameter> or <parameter>rowdesc</parameter> is - <symbol>NULL</symbol> + <type>HeapTupleHeader</type> pointing to copied row, + or <symbol>NULL</symbol> on error + (see <varname>SPI_result</varname> for an error indication) </para> </refsect1> </refentry> @@ -3735,6 +3959,13 @@ HeapTuple SPI_modifytuple(Relation <parameter>rel</parameter>, HeapTuple <parame <function>SPI_modifytuple</function> creates a new row by substituting new values for selected columns, copying the original row's columns at other positions. The input row is not modified. + The new row is returned in the upper executor context. + </para> + + <para> + This function can only be used while connected to SPI. + Otherwise, it returns NULL and sets <varname>SPI_result</varname> to + <symbol>SPI_ERROR_UNCONNECTED</symbol>. </para> </refsect1> @@ -3820,8 +4051,8 @@ HeapTuple SPI_modifytuple(Relation <parameter>rel</parameter>, HeapTuple <parame <para> new row with modifications, allocated in the upper executor - context; <symbol>NULL</symbol> only if <parameter>row</parameter> - is <symbol>NULL</symbol> + context, or <symbol>NULL</symbol> on error + (see <varname>SPI_result</varname> for an error indication) </para> <para> @@ -3844,11 +4075,20 @@ HeapTuple SPI_modifytuple(Relation <parameter>rel</parameter>, HeapTuple <parame <listitem> <para> if <parameter>colnum</> contains an invalid column number (less - than or equal to 0 or greater than the number of column in + than or equal to 0 or greater than the number of columns in <parameter>row</>) </para> </listitem> </varlistentry> + + <varlistentry> + <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term> + <listitem> + <para> + if SPI is not active + </para> + </listitem> + </varlistentry> </variablelist> </para> </refsect1> diff --git a/doc/src/sgml/sql.sgml b/doc/src/sgml/sql.sgml deleted file mode 100644 index 315eb0b7f7..0000000000 --- a/doc/src/sgml/sql.sgml +++ /dev/null @@ -1,2153 +0,0 @@ -<!-- doc/src/sgml/sql.sgml --> - - <chapter id="sql-intro"> - <title>SQL</title> - - <abstract> - <para> - This chapter introduces the mathematical concepts behind - relational databases. It is not required reading, so if you bog - down or want to get straight to some simple examples feel free to - jump ahead to the next chapter and come back when you have more - time and patience. This stuff is supposed to be fun! - </para> - - <para> - This material originally appeared as a part of - Stefan Simkovics' Master's Thesis - (<xref linkend="SIM98" endterm="SIM98">). - </para> - </abstract> - - <para> - <acronym>SQL</acronym> has become the most popular relational query - language. - The name <quote><acronym>SQL</acronym></quote> is an abbreviation for - <firstterm>Structured Query Language</firstterm>. - In 1974 Donald Chamberlin and others defined the - language SEQUEL (<firstterm>Structured English Query - Language</firstterm>) at IBM - Research. This language was first implemented in an IBM - prototype called SEQUEL-XRM in 1974-75. In 1976-77 a revised version - of SEQUEL called SEQUEL/2 was defined and the name was changed to - <acronym>SQL</acronym> - subsequently. - </para> - - <para> - A new prototype called System R was developed by IBM in 1977. System R - implemented a large subset of SEQUEL/2 (now <acronym>SQL</acronym>) - and a number of - changes were made to <acronym>SQL</acronym> during the project. - System R was installed in - a number of user sites, both internal IBM sites and also some selected - customer sites. Thanks to the success and acceptance of System R at - those user sites IBM started to develop commercial products that - implemented the <acronym>SQL</acronym> language based on the System - R technology. - </para> - - <para> - Over the next years IBM and also a number of other vendors announced - <acronym>SQL</acronym> products such as - <productname>SQL/DS</productname> (IBM), - <productname>DB2</productname> (IBM), - <productname>ORACLE</productname> (Oracle Corp.), - <productname>DG/SQL</productname> (Data General Corp.), - and <productname>SYBASE</productname> (Sybase Inc.). - </para> - - <para> - <acronym>SQL</acronym> is also an official standard now. In 1982 - the American National - Standards Institute (<acronym>ANSI</acronym>) chartered its - Database Committee X3H2 to - develop a proposal for a standard relational language. This proposal - was ratified in 1986 and consisted essentially of the IBM dialect of - <acronym>SQL</acronym>. In 1987 this <acronym>ANSI</acronym> - standard was also accepted as an international - standard by the International Organization for Standardization - (<acronym>ISO</acronym>). - This original standard version of <acronym>SQL</acronym> is often - referred to, - informally, as <quote><abbrev>SQL/86</abbrev></quote>. In 1989 the original - standard was extended - and this new standard is often, again informally, referred to as - <quote><abbrev>SQL/89</abbrev></quote>. Also in 1989, a related standard called - <firstterm>Database Language Embedded <acronym>SQL</acronym></firstterm> - (<acronym>ESQL</acronym>) was developed. - </para> - - <para> - The <acronym>ISO</acronym> and <acronym>ANSI</acronym> committees - have been working for many years on the - definition of a greatly expanded version of the original standard, - referred to informally as <firstterm><acronym>SQL2</acronym></firstterm> - or <firstterm><acronym>SQL/92</acronym></firstterm>. This version became a - ratified standard - <quote>International Standard ISO/IEC 9075:1992, - Database Language <acronym>SQL</acronym></quote> - in late 1992. - <acronym>SQL/92</acronym> is the version - normally meant when people refer to <quote>the <acronym>SQL</acronym> - standard</quote>. A detailed - description of <acronym>SQL/92</acronym> is given in - <xref linkend="DATE97" endterm="DATE97">. At the time of - writing this document a new standard informally referred to - as <firstterm><acronym>SQL3</acronym></firstterm> - is under development. It is planned to make <acronym>SQL</acronym> - a Turing-complete - language, i.e., all computable queries (e.g., recursive queries) will be - possible. This has now been completed as SQL:2003. - </para> - - <sect1 id="rel-model"> - <title>The Relational Data Model</title> - - <para> - As mentioned before, <acronym>SQL</acronym> is a relational - language. That means it is - based on the <firstterm>relational data model</firstterm> - first published by E.F. Codd in - 1970. We will give a formal description of the relational model - later (in - <xref linkend="formal-notion" endterm="formal-notion">) - but first we want to have a look at it from a more intuitive - point of view. - </para> - - <para> - A <firstterm>relational database</firstterm> is a database that is - perceived by its - users as a <firstterm>collection of tables</firstterm> (and - nothing else but tables). - A table consists of rows and columns where each row represents a - record and each column represents an attribute of the records - contained in the table. - <xref linkend="supplier-fig" endterm="supplier-fig"> - shows an example of a database consisting of three tables: - - <itemizedlist> - <listitem> - <para> - SUPPLIER is a table storing the number - (SNO), the name (SNAME) and the city (CITY) of a supplier. - </para> - </listitem> - - <listitem> - <para> - PART is a table storing the number (PNO) the name (PNAME) and - the price (PRICE) of a part. - </para> - </listitem> - - <listitem> - <para> - SELLS stores information about which part (PNO) is sold by which - supplier (SNO). - It serves in a sense to connect the other two tables together. - </para> - </listitem> - </itemizedlist> - - <example> - <title id="supplier-fig">The Suppliers and Parts Database</title> -<screen> -SUPPLIER: SELLS: - SNO | SNAME | CITY SNO | PNO -----+---------+-------- -----+----- - 1 | Smith | London 1 | 1 - 2 | Jones | Paris 1 | 2 - 3 | Adams | Vienna 2 | 4 - 4 | Blake | Rome 3 | 1 - 3 | 3 - 4 | 2 -PART: 4 | 3 - PNO | PNAME | PRICE 4 | 4 -----+---------+--------- - 1 | Screw | 10 - 2 | Nut | 8 - 3 | Bolt | 15 - 4 | Cam | 25 -</screen> - </example> - </para> - - <para> - The tables PART and SUPPLIER can be regarded as - <firstterm>entities</firstterm> and - SELLS can be regarded as a <firstterm>relationship</firstterm> - between a particular - part and a particular supplier. - </para> - - <para> - As we will see later, <acronym>SQL</acronym> operates on tables - like the ones just - defined but before that we will study the theory of the relational - model. - </para> - </sect1> - - <sect1 id="relmodel-formal"> - <title id="formal-notion">Relational Data Model Formalities</title> - - <para> - The mathematical concept underlying the relational model is the - set-theoretic <firstterm>relation</firstterm> which is a subset of - the Cartesian - product of a list of domains. This set-theoretic relation gives - the model its name (do not confuse it with the relationship from the - <firstterm>Entity-Relationship model</firstterm>). - Formally a domain is simply a set of - values. For example the set of integers is a domain. Also the set of - character strings of length 20 and the real numbers are examples of - domains. - </para> - - <para> -<!-- -\begin{definition} -The <firstterm>Cartesian product</firstterm> of domains $D_{1}, - D_{2},\ldots, D_{k}$ written -\mbox{$D_{1} \times D_{2} \times \ldots \times D_{k}$} is the set of -all $k$-tuples $(v_{1},v_{2},\ldots,v_{k})$ such that \mbox{$v_{1} \in -D_{1}, v_{2} \in D_{2}, \ldots, v_{k} \in D_{k}$}. -\end{definition} ---> - The <firstterm>Cartesian product</firstterm> of domains - <parameter>D<subscript>1</subscript></parameter>, - <parameter>D<subscript>2</subscript></parameter>, - ... - <parameter>D<subscript>k</subscript></parameter>, - written - <parameter>D<subscript>1</subscript></parameter> × - <parameter>D<subscript>2</subscript></parameter> × - ... × - <parameter>D<subscript>k</subscript></parameter> - is the set of all k-tuples - <parameter>v<subscript>1</subscript></parameter>, - <parameter>v<subscript>2</subscript></parameter>, - ... - <parameter>v<subscript>k</subscript></parameter>, - such that - <parameter>v<subscript>1</subscript></parameter> ∈ - <parameter>D<subscript>1</subscript></parameter>, - <parameter>v<subscript>2</subscript></parameter> ∈ - <parameter>D<subscript>2</subscript></parameter>, - ... - <parameter>v<subscript>k</subscript></parameter> ∈ - <parameter>D<subscript>k</subscript></parameter>. - </para> - - <para> - For example, when we have -<!-- - $k=2$, $D_{1}=\{0,1\}$ and -$D_{2}=\{a,b,c\}$, then $D_{1} \times D_{2}$ is -$\{(0,a),(0,b),(0,c),(1,a),(1,b),(1,c)\}$. ---> - <parameter>k</parameter>=2, - <parameter>D<subscript>1</subscript></parameter>=<literal>{0,1}</literal> and - <parameter>D<subscript>2</subscript></parameter>=<literal>{a,b,c}</literal> then - <parameter>D<subscript>1</subscript></parameter> × - <parameter>D<subscript>2</subscript></parameter> is - <literal>{(0,a),(0,b),(0,c),(1,a),(1,b),(1,c)}</literal>. - </para> - - <para> -<!-- -\begin{definition} -A Relation is any subset of the Cartesian product of one or more -domains: $R \subseteq$ \mbox{$D_{1} \times D_{2} \times \ldots \times D_{k}$} -\end{definition} ---> - A Relation is any subset of the Cartesian product of one or more - domains: <parameter>R</parameter> ⊆ - <parameter>D<subscript>1</subscript></parameter> × - <parameter>D<subscript>2</subscript></parameter> × - ... × - <parameter>D<subscript>k</subscript></parameter>. - </para> - - <para> - For example <literal>{(0,a),(0,b),(1,a)}</literal> is a relation; - it is in fact a subset of - <parameter>D<subscript>1</subscript></parameter> × - <parameter>D<subscript>2</subscript></parameter> - mentioned above. - </para> - - <para> - The members of a relation are called tuples. Each relation of some - Cartesian product - <parameter>D<subscript>1</subscript></parameter> × - <parameter>D<subscript>2</subscript></parameter> × - ... × - <parameter>D<subscript>k</subscript></parameter> - is said to have arity <literal>k</literal> and is therefore a set - of <literal>k</literal>-tuples. - </para> - - <para> - A relation can be viewed as a table (as we already did, remember - <xref linkend="supplier-fig" endterm="supplier-fig"> where - every tuple is represented by a row and every column corresponds to - one component of a tuple. Giving names (called attributes) to the - columns leads to the definition of a - <firstterm>relation scheme</firstterm>. - </para> - - <para> -<!-- -\begin{definition} -A {\it relation scheme} $R$ is a finite set of attributes -\mbox{$\{A_{1},A_{2},\ldots,A_{k}\}$}. There is a domain $D_{i}$ for -each attribute $A_{i}, 1 \le i \le k$ where the values of the -attributes are taken from. We often write a relation scheme as -\mbox{$R(A_{1},A_{2},\ldots,A_{k})$}. -\end{definition} ---> - A <firstterm>relation scheme</firstterm> <literal>R</literal> is a - finite set of attributes - <parameter>A<subscript>1</subscript></parameter>, - <parameter>A<subscript>2</subscript></parameter>, - ... - <parameter>A<subscript>k</subscript></parameter>. - There is a domain - <parameter>D<subscript>i</subscript></parameter>, - for each attribute - <parameter>A<subscript>i</subscript></parameter>, - 1 <= <literal>i</literal> <= <literal>k</literal>, - where the values of the attributes are taken from. We often write - a relation scheme as - <literal>R(<parameter>A<subscript>1</subscript></parameter>, - <parameter>A<subscript>2</subscript></parameter>, - ... - <parameter>A<subscript>k</subscript></parameter>)</literal>. - - <note> - <para> - A <firstterm>relation scheme</firstterm> is just a kind of template - whereas a <firstterm>relation</firstterm> is an instance of a - <firstterm>relation - scheme</firstterm>. The relation consists of tuples (and can - therefore be - viewed as a table); not so the relation scheme. - </para> - </note> - </para> - - <sect2> - <title id="domains">Domains vs. Data Types</title> - - <para> - We often talked about <firstterm>domains</firstterm> - in the last section. Recall that a - domain is, formally, just a set of values (e.g., the set of integers or - the real numbers). In terms of database systems we often talk of - <firstterm>data types</firstterm> instead of domains. - When we define a table we have to make - a decision about which attributes to include. Additionally we - have to decide which kind of data is going to be stored as - attribute values. For example the values of - <classname>SNAME</classname> from the table - <classname>SUPPLIER</classname> will be character strings, - whereas <classname>SNO</classname> will store - integers. We define this by assigning a data type to each - attribute. The type of <classname>SNAME</classname> will be - <type>VARCHAR(20)</type> (this is the <acronym>SQL</acronym> type - for character strings of length <= 20), - the type of <classname>SNO</classname> will be - <type>INTEGER</type>. With the assignment of a data type we also - have selected - a domain for an attribute. The domain of - <classname>SNAME</classname> is the set of all - character strings of length <= 20, - the domain of <classname>SNO</classname> is the set of - all integer numbers. - </para> - </sect2> - </sect1> - - <sect1 id="relmodel-oper"> - <title id="operations">Operations in the Relational Data Model</title> - - <para> - In the previous section - (<xref linkend="formal-notion" endterm="formal-notion">) - we defined the mathematical notion of - the relational model. Now we know how the data can be stored using a - relational data model but we do not know what to do with all these - tables to retrieve something from the database yet. For example somebody - could ask for the names of all suppliers that sell the part - 'Screw'. Therefore two rather different kinds of notations for - expressing operations on relations have been defined: - - <itemizedlist> - <listitem> - <para> - The <firstterm>Relational Algebra</firstterm> which is an - algebraic notation, - where queries are expressed by applying specialized operators to the - relations. - </para> - </listitem> - - <listitem> - <para> - The <firstterm>Relational Calculus</firstterm> which is a - logical notation, - where queries are expressed by formulating some logical restrictions - that the tuples in the answer must satisfy. - </para> - </listitem> - </itemizedlist> - </para> - - <sect2> - <title id="rel-alg">Relational Algebra</title> - - <para> - The <firstterm>Relational Algebra</firstterm> was introduced by - E. F. Codd in 1972. It consists of a set of operations on relations: - - <itemizedlist> - <listitem> - <para> - SELECT (σ): extracts <firstterm>tuples</firstterm> from - a relation that - satisfy a given restriction. Let <parameter>R</parameter> be a - table that contains an attribute - <parameter>A</parameter>. -σ<subscript>A=a</subscript>(R) = {t ∈ R ∣ t(A) = a} - where <literal>t</literal> denotes a - tuple of <parameter>R</parameter> and <literal>t(A)</literal> - denotes the value of attribute <parameter>A</parameter> of - tuple <literal>t</literal>. - </para> - </listitem> - - <listitem> - <para> - PROJECT (π): extracts specified - <firstterm>attributes</firstterm> (columns) from a - relation. Let <classname>R</classname> be a relation - that contains an attribute <classname>X</classname>. - π<subscript>X</subscript>(<classname>R</classname>) = {t(X) ∣ t ∈ <classname>R</classname>}, - where <literal>t</literal>(<classname>X</classname>) denotes the value of - attribute <classname>X</classname> of tuple <literal>t</literal>. - </para> - </listitem> - - <listitem> - <para> - PRODUCT (×): builds the Cartesian product of two - relations. Let <classname>R</classname> be a table with arity - <literal>k</literal><subscript>1</subscript> and let - <classname>S</classname> be a table with - arity <literal>k</literal><subscript>2</subscript>. - <classname>R</classname> × <classname>S</classname> - is the set of all - <literal>k</literal><subscript>1</subscript> - + <literal>k</literal><subscript>2</subscript>-tuples - whose first <literal>k</literal><subscript>1</subscript> - components form a tuple in <classname>R</classname> and whose last - <literal>k</literal><subscript>2</subscript> components form a - tuple in <classname>S</classname>. - </para> - </listitem> - - <listitem> - <para> - UNION (∪): builds the set-theoretic union of two - tables. Given the tables <classname>R</classname> and - <classname>S</classname> (both must have the same arity), - the union <classname>R</classname> ∪ <classname>S</classname> - is the set of tuples that are in <classname>R</classname> - or <classname>S</classname> or both. - </para> - </listitem> - - <listitem> - <para> - INTERSECT (∩): builds the set-theoretic intersection of two - tables. Given the tables <classname>R</classname> and - <classname>S</classname>, - <classname>R</classname> ∩ <classname>S</classname> is the - set of tuples - that are in <classname>R</classname> and in - <classname>S</classname>. - We again require that <classname>R</classname> and - <classname>S</classname> have the - same arity. - </para> - </listitem> - - <listitem> - <para> - DIFFERENCE (− or ∖): builds the set difference of - two tables. Let <classname>R</classname> and <classname>S</classname> - again be two tables with the same - arity. <classname>R</classname> - <classname>S</classname> - is the set of tuples in <classname>R</classname> but not in - <classname>S</classname>. - </para> - </listitem> - - <listitem> - <para> - JOIN (∏): connects two tables by their common - attributes. Let <classname>R</classname> be a table with the - attributes <classname>A</classname>,<classname>B</classname> - and <classname>C</classname> and - let <classname>S</classname> be a table with the attributes - <classname>C</classname>,<classname>D</classname> - and <classname>E</classname>. There is one - attribute common to both relations, - the attribute <classname>C</classname>. -<!-- - <classname>R</classname> ∏ <classname>S</classname> = - π<subscript><classname>R</classname>.<classname>A</classname>,<classname>R</classname>.<classname>B</classname>,<classname>R</classname>.<classname>C</classname>,<classname>S</classname>.<classname>D</classname>,<classname>S</classname>.<classname>E</classname></subscript>(σ<subscript><classname>R</classname>.<classname>C</classname>=<classname>S</classname>.<classname>C</classname></subscript>(<classname>R</classname> × <classname>S</classname>)). ---> - R ∏ S = π<subscript>R.A,R.B,R.C,S.D,S.E</subscript>(σ<subscript>R.C=S.C</subscript>(R × S)). - What are we doing here? We first calculate the Cartesian - product - <classname>R</classname> × <classname>S</classname>. - Then we select those tuples whose values for the common - attribute <classname>C</classname> are equal - (σ<subscript>R.C = S.C</subscript>). - Now we have a table - that contains the attribute <classname>C</classname> - two times and we correct this by - projecting out the duplicate column. - </para> - - <example> - <title id="join-example">An Inner Join</title> - - <para> - Let's have a look at the tables that are produced by evaluating the steps - necessary for a join. - Let the following two tables be given: - -<screen> -R: S: - A | B | C C | D | E ----+---+--- ---+---+--- - 1 | 2 | 3 3 | a | b - 4 | 5 | 6 6 | c | d - 7 | 8 | 9 -</screen> - </para> - </example> - - <para> - First we calculate the Cartesian product - <classname>R</classname> × <classname>S</classname> and - get: - -<screen> -R x S: - A | B | R.C | S.C | D | E ----+---+-----+-----+---+--- - 1 | 2 | 3 | 3 | a | b - 1 | 2 | 3 | 6 | c | d - 4 | 5 | 6 | 3 | a | b - 4 | 5 | 6 | 6 | c | d - 7 | 8 | 9 | 3 | a | b - 7 | 8 | 9 | 6 | c | d -</screen> - </para> - - <para> - After the selection - σ<subscript>R.C=S.C</subscript>(R × S) - we get: - -<screen> - A | B | R.C | S.C | D | E ----+---+-----+-----+---+--- - 1 | 2 | 3 | 3 | a | b - 4 | 5 | 6 | 6 | c | d -</screen> - </para> - - <para> - To remove the duplicate column - <classname>S</classname>.<classname>C</classname> - we project it out by the following operation: - π<subscript>R.A,R.B,R.C,S.D,S.E</subscript>(σ<subscript>R.C=S.C</subscript>(R × S)) - and get: - -<screen> - A | B | C | D | E ----+---+---+---+--- - 1 | 2 | 3 | a | b - 4 | 5 | 6 | c | d -</screen> - </para> - </listitem> - - <listitem> - <para> - DIVIDE (÷): Let <classname>R</classname> be a table - with the attributes A, B, C, and D and let - <classname>S</classname> be a table with the attributes - C and D. - Then we define the division as: - -<programlisting> -R ÷ S = {t ∣ ∀ t<subscript>s</subscript> ∈ S ∃ t<subscript>r</subscript> ∈ R -</programlisting> - - such that -t<subscript>r</subscript>(A,B)=t∧t<subscript>r</subscript>(C,D)=t<subscript>s</subscript>} - where - t<subscript>r</subscript>(x,y) - denotes a - tuple of table <classname>R</classname> that consists only of - the components <literal>x</literal> and <literal>y</literal>. - Note that the tuple <literal>t</literal> only consists of the - components <classname>A</classname> and - <classname>B</classname> of relation <classname>R</classname>. - </para> - - <para id="divide-example"> - Given the following tables - -<screen> -R: S: - A | B | C | D C | D ----+---+---+--- ---+--- - a | b | c | d c | d - a | b | e | f e | f - b | c | e | f - e | d | c | d - e | d | e | f - a | b | d | e -</screen> - - R ÷ S - is derived as - -<screen> - A | B ----+--- - a | b - e | d -</screen> - </para> - </listitem> - </itemizedlist> - </para> - - <para> - For a more detailed description and definition of the relational - algebra refer to [<xref linkend="ULL88" endterm="ULL88">] or - [<xref linkend="DATE04" endterm="DATE04">]. - </para> - - <example> - <title id="suppl-rel-alg">A Query Using Relational Algebra</title> - <para> - Recall that we formulated all those relational operators to be able to - retrieve data from the database. Let's return to our example from - the previous - section (<xref linkend="operations" endterm="operations">) - where someone wanted to know the names of all - suppliers that sell the part <literal>Screw</literal>. - This question can be answered - using relational algebra by the following operation: - -<programlisting> -π<subscript>SUPPLIER.SNAME</subscript>(σ<subscript>PART.PNAME='Screw'</subscript>(SUPPLIER ∏ SELLS ∏ PART)) -</programlisting> - </para> - - <para> - We call such an operation a query. If we evaluate the above query - against the our example tables - (<xref linkend="supplier-fig" endterm="supplier-fig">) - we will obtain the following result: - -<screen> - SNAME -------- - Smith - Adams -</screen> - </para> - </example> - </sect2> - - <sect2 id="rel-calc"> - <title>Relational Calculus</title> - - <para> - The relational calculus is based on the - <firstterm>first order logic</firstterm>. There are - two variants of the relational calculus: - - <itemizedlist> - <listitem> - <para> - The <firstterm>Domain Relational Calculus</firstterm> - (<acronym>DRC</acronym>), where variables - stand for components (attributes) of the tuples. - </para> - </listitem> - - <listitem> - <para> - The <firstterm>Tuple Relational Calculus</firstterm> - (<acronym>TRC</acronym>), where variables stand for tuples. - </para> - </listitem> - </itemizedlist> - </para> - - <para> - We want to discuss the tuple relational calculus only because it is - the one underlying the most relational languages. For a detailed - discussion on <acronym>DRC</acronym> (and also - <acronym>TRC</acronym>) see - <xref linkend="DATE04" endterm="DATE04"> - or - <xref linkend="ULL88" endterm="ULL88">. - </para> - </sect2> - - <sect2> - <title>Tuple Relational Calculus</title> - - <para> - The queries used in <acronym>TRC</acronym> are of the following - form: - -<programlisting> -x(A) ∣ F(x) -</programlisting> - - where <literal>x</literal> is a tuple variable - <classname>A</classname> is a set of attributes and <literal>F</literal> is a - formula. The resulting relation consists of all tuples - <literal>t(A)</literal> that satisfy <literal>F(t)</literal>. - </para> - - <para> - If we want to answer the question from example - <xref linkend="suppl-rel-alg" endterm="suppl-rel-alg"> - using <acronym>TRC</acronym> we formulate the following query: - -<programlisting> -{x(SNAME) ∣ x ∈ SUPPLIER ∧ - ∃ y ∈ SELLS ∃ z ∈ PART (y(SNO)=x(SNO) ∧ - z(PNO)=y(PNO) ∧ - z(PNAME)='Screw')} -</programlisting> - </para> - - <para> - Evaluating the query against the tables from - <xref linkend="supplier-fig" endterm="supplier-fig"> - again leads to the same result - as in - <xref linkend="suppl-rel-alg" endterm="suppl-rel-alg">. - </para> - </sect2> - - <sect2 id="alg-vs-calc"> - <title>Relational Algebra vs. Relational Calculus</title> - - <para> - The relational algebra and the relational calculus have the same - <firstterm>expressive power</firstterm>; i.e., all queries that - can be formulated using relational algebra can also be formulated - using the relational calculus and vice versa. - This was first proved by E. F. Codd in - 1972. This proof is based on an algorithm (<quote>Codd's reduction - algorithm</quote>) by which an arbitrary expression of the relational - calculus can be reduced to a semantically equivalent expression of - relational algebra. For a more detailed discussion on that refer to - <xref linkend="DATE04" endterm="DATE04"> - and - <xref linkend="ULL88" endterm="ULL88">. - </para> - - <para> - It is sometimes said that languages based on the relational - calculus are <quote>higher level</quote> or <quote>more - declarative</quote> than languages based on relational algebra - because the algebra (partially) specifies the order of operations - while the calculus leaves it to a compiler or interpreter to - determine the most efficient order of evaluation. - </para> - </sect2> - </sect1> - - <sect1 id="sql-language"> - <title>The <acronym>SQL</acronym> Language</title> - - <para> - As is the case with most modern relational languages, - <acronym>SQL</acronym> is based on the tuple - relational calculus. As a result every query that can be formulated - using the tuple relational calculus (or equivalently, relational - algebra) can also be formulated using - <acronym>SQL</acronym>. There are, however, - capabilities beyond the scope of relational algebra or calculus. Here - is a list of some additional features provided by - <acronym>SQL</acronym> that are not - part of relational algebra or calculus: - - <itemizedlist> - <listitem> - <para> - Commands for insertion, deletion or modification of data. - </para> - </listitem> - - <listitem> - <para> - Arithmetic capability: In <acronym>SQL</acronym> it is possible - to involve - arithmetic operations as well as comparisons, e.g.: - -<programlisting> -A < B + 3. -</programlisting> - - Note - that + or other arithmetic operators appear neither in relational - algebra nor in relational calculus. - </para> - </listitem> - - <listitem> - <para> - Assignment and Print Commands: It is possible to print a - relation constructed by a query and to assign a computed relation to a - relation name. - </para> - </listitem> - - <listitem> - <para> - Aggregate Functions: Operations such as - <firstterm>average</firstterm>, <firstterm>sum</firstterm>, - <firstterm>max</firstterm>, etc. can be applied to columns of a - relation to - obtain a single quantity. - </para> - </listitem> - </itemizedlist> - </para> - - <sect2 id="select"> - <title id="select-title">Select</title> - - <para> - The most often used command in <acronym>SQL</acronym> is the - <command>SELECT</command> statement, - used to retrieve data. The syntax is: - -<synopsis> -SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replaceable> [, ...] ) ] ] - * | <replaceable class="PARAMETER">expression</replaceable> [ [ AS ] <replaceable class="PARAMETER">output_name</replaceable> ] [, ...] - [ INTO [ TEMPORARY | TEMP ] [ TABLE ] <replaceable class="PARAMETER">new_table</replaceable> ] - [ FROM <replaceable class="PARAMETER">from_item</replaceable> [, ...] ] - [ WHERE <replaceable class="PARAMETER">condition</replaceable> ] - [ GROUP BY <replaceable class="PARAMETER">expression</replaceable> [, ...] ] - [ HAVING <replaceable class="PARAMETER">condition</replaceable> [, ...] ] - [ { UNION | INTERSECT | EXCEPT } [ ALL ] <replaceable class="PARAMETER">select</replaceable> ] - [ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [ NULLS { FIRST | LAST } ] [, ...] ] - [ LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } ] - [ OFFSET <replaceable class="PARAMETER">start</replaceable> ] - [ FOR { UPDATE | SHARE } [ OF <replaceable class="parameter">table_name</replaceable> [, ...] ] [ NOWAIT | SKIP LOCKED ] [...] ] -</synopsis> - </para> - - <para> - Now we will illustrate the complex syntax of the - <command>SELECT</command> statement with various examples. The - tables used for the examples are defined in <xref - linkend="supplier-fig" endterm="supplier-fig">. - </para> - - <sect3> - <title>Simple Selects</title> - - <para> - Here are some simple examples using a <command>SELECT</command> statement: - - <example> - <title id="simple-query">Simple Query with Qualification</title> - <para> - To retrieve all tuples from table PART where the attribute PRICE is - greater than 10 we formulate the following query: - -<programlisting> -SELECT * FROM PART - WHERE PRICE > 10; -</programlisting> - - and get the table: - -<screen> - PNO | PNAME | PRICE ------+---------+-------- - 3 | Bolt | 15 - 4 | Cam | 25 -</screen> - </para> - - <para> - Using <quote>*</quote> in the <command>SELECT</command> statement - will deliver all attributes from the table. If we want to retrieve - only the attributes PNAME and PRICE from table PART we use the - statement: - -<programlisting> -SELECT PNAME, PRICE - FROM PART - WHERE PRICE > 10; -</programlisting> - - In this case the result is: - -<screen> - PNAME | PRICE - --------+-------- - Bolt | 15 - Cam | 25 -</screen> - - Note that the <acronym>SQL</acronym> <command>SELECT</command> - corresponds to the <quote>projection</quote> in relational algebra - not to the <quote>selection</quote> (see <xref linkend="rel-alg" - endterm="rel-alg"> for more details). - </para> - - <para> - The qualifications in the WHERE clause can also be logically connected - using the keywords OR, AND, and NOT: - -<programlisting> -SELECT PNAME, PRICE - FROM PART - WHERE PNAME = 'Bolt' AND - (PRICE = 0 OR PRICE <= 15); -</programlisting> - - will lead to the result: - -<screen> - PNAME | PRICE ---------+-------- - Bolt | 15 -</screen> - </para> - - <para> - Arithmetic operations can be used in the target list and in the WHERE - clause. For example if we want to know how much it would cost if we - take two pieces of a part we could use the following query: - -<programlisting> -SELECT PNAME, PRICE * 2 AS DOUBLE - FROM PART - WHERE PRICE * 2 < 50; -</programlisting> - - and we get: - -<screen> - PNAME | DOUBLE ---------+--------- - Screw | 20 - Nut | 16 - Bolt | 30 -</screen> - - Note that the word DOUBLE after the keyword AS is the new title of the - second column. This technique can be used for every element of the - target list to assign a new title to the resulting - column. This new title - is often referred to as alias. The alias cannot be used throughout the - rest of the query. - </para> - </example> - </para> - </sect3> - - <sect3> - <title>Joins</title> - - <para id="simple-join"> - The following example shows how <firstterm>joins</firstterm> are - realized in <acronym>SQL</acronym>. - </para> - - <para> - To join the three tables SUPPLIER, PART and SELLS over their common - attributes we formulate the following statement: - -<programlisting> -SELECT S.SNAME, P.PNAME - FROM SUPPLIER S, PART P, SELLS SE - WHERE S.SNO = SE.SNO AND - P.PNO = SE.PNO; -</programlisting> - - and get the following table as a result: - -<screen> - SNAME | PNAME --------+------- - Smith | Screw - Smith | Nut - Jones | Cam - Adams | Screw - Adams | Bolt - Blake | Nut - Blake | Bolt - Blake | Cam -</screen> - </para> - - <para> - In the FROM clause we introduced an alias name for every relation - because there are common named attributes (SNO and PNO) among the - relations. Now we can distinguish between the common named attributes - by simply prefixing the attribute name with the alias name followed by - a dot. The join is calculated in the same way as shown in - <xref linkend="join-example" endterm="join-example">. - First the Cartesian product - - SUPPLIER × PART × SELLS - - is derived. Now only those tuples satisfying the - conditions given in the WHERE clause are selected (i.e., the common - named attributes have to be equal). Finally we project out all - columns but S.SNAME and P.PNAME. - </para> - - <para> - Another way to perform joins is to use the SQL JOIN syntax as follows: -<programlisting> -SELECT sname, pname from supplier - JOIN sells USING (sno) - JOIN part USING (pno); -</programlisting> - giving again: -<screen> - sname | pname --------+------- - Smith | Screw - Adams | Screw - Smith | Nut - Blake | Nut - Adams | Bolt - Blake | Bolt - Jones | Cam - Blake | Cam -(8 rows) -</screen> - </para> - - <para> - A joined table, created using JOIN syntax, is a table reference list - item that occurs in a FROM clause and before any WHERE, GROUP BY, - or HAVING clause. Other table references, including table names or - other JOIN clauses, can be included in the FROM clause if separated - by commas. JOINed tables are logically like any other - table listed in the FROM clause. - </para> - - <para> - SQL JOINs come in two main types, CROSS JOINs (unqualified joins) - and <firstterm>qualified JOINs</>. Qualified joins can be further - subdivided based on the way in which the <firstterm>join condition</> - is specified (ON, USING, or NATURAL) and the way in which it is - applied (INNER or OUTER join). - </para> - - <variablelist> - <title>Join Types</title> - <varlistentry> - <term>CROSS JOIN</term> - <listitem> - <cmdsynopsis> - <arg choice="req"> <replaceable class="parameter">T1</replaceable> </arg> - <command> CROSS JOIN </command> - <arg choice="req"> <replaceable class="parameter">T2</replaceable> </arg> - </cmdsynopsis> - - <para> - A cross join takes two tables T1 and T2 having N and M rows - respectively, and returns a joined table containing all - N*M possible joined rows. For each row R1 of T1, each row - R2 of T2 is joined with R1 to yield a joined table row JR - consisting of all fields in R1 and R2. A CROSS JOIN is - equivalent to an INNER JOIN ON TRUE. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Qualified JOINs</term> - <listitem> - - <cmdsynopsis> - <arg choice="req"> <replaceable class="parameter">T1</replaceable> </arg> - <arg choice="opt"> NATURAL </arg> - <group choice="opt"> - <arg choice="opt"> INNER </arg> - <arg choice="plain"> - <group choice="req"> - <arg choice="plain"> LEFT </arg> - <arg choice="plain"> RIGHT </arg> - <arg choice="plain"> FULL </arg> - </group> - <arg choice="opt"> OUTER </arg> - </arg> - </group> - <command> JOIN </command> - <arg choice="req"> <replaceable class="parameter">T2</replaceable> </arg> - <group choice="req"> - <arg choice="plain"> ON <replaceable>search condition</replaceable></arg> - <arg choice="plain"> USING ( <replaceable>join column list</replaceable> ) </arg> - </group> - </cmdsynopsis> - - <para> - A qualified JOIN must specify its join condition - by providing one (and only one) of NATURAL, ON, or - USING. The ON clause - takes a <replaceable>search condition</replaceable>, - which is the same as in a WHERE clause. The USING - clause takes a comma-separated list of column names, - which the joined tables must have in common, and joins - the tables on equality of those columns. NATURAL is - shorthand for a USING clause that lists all the common - column names of the two tables. A side-effect of both - USING and NATURAL is that only one copy of each joined - column is emitted into the result table (compare the - relational-algebra definition of JOIN, shown earlier). - </para> - - <!-- begin join semantics --> - <variablelist> - <varlistentry> - <term> - <cmdsynopsis> - <arg choice="opt"> INNER </arg> - <command> JOIN </command> - </cmdsynopsis> - </term> - <listitem> - <para> - For each row R1 of T1, the joined table has a row for each row - in T2 that satisfies the join condition with R1. - </para> - <tip> - <para> - The words INNER and OUTER are optional for all JOINs. - INNER is the default. LEFT, RIGHT, and FULL imply an - OUTER JOIN. - </para> - </tip> - </listitem> - </varlistentry> - <varlistentry> - <term> - <cmdsynopsis> - <arg choice="plain"> LEFT </arg> - <arg choice="opt"> OUTER </arg> - <command> JOIN </command> - </cmdsynopsis> - </term> - <listitem> - <para> - First, an INNER JOIN is performed. - Then, for each row in T1 that does not satisfy the join - condition with any row in T2, an additional joined row is - returned with null fields in the columns from T2. - </para> - <tip> - <para> - The joined table unconditionally has a row for each row in T1. - </para> - </tip> - </listitem> - </varlistentry> - <varlistentry> - <term> - <cmdsynopsis> - <arg choice="plain"> RIGHT </arg> - <arg choice="opt"> OUTER </arg> - <command> JOIN </command> - </cmdsynopsis> - </term> - <listitem> - <para> - First, an INNER JOIN is performed. - Then, for each row in T2 that does not satisfy the join - condition with any row in T1, an additional joined row is - returned with null fields in the columns from T1. - </para> - <tip> - <para> - The joined table unconditionally has a row for each row in T2. - </para> - </tip> - </listitem> - </varlistentry> - <varlistentry> - <term> - <cmdsynopsis> - <arg choice="plain"> FULL </arg> - <arg choice="opt"> OUTER </arg> - <command> JOIN </command> - </cmdsynopsis> - </term> - <listitem> - <para> - First, an INNER JOIN is performed. - Then, for each row in T1 that does not satisfy the join - condition with any row in T2, an additional joined row is - returned with null fields in the columns from T2. - Also, for each row in T2 that does not satisfy the join - condition with any row in T1, an additional joined row is - returned with null fields in the columns from T1. - </para> - <tip> - <para> - The joined table unconditionally has a row for every row of T1 - and a row for every row of T2. - </para> - </tip> - </listitem> - </varlistentry> - </variablelist> - <!-- end join semantics --> - - </listitem> - </varlistentry> - </variablelist> - - <para> - JOINs of all types can be chained together or nested where either or both of - <replaceable class="parameter">T1</replaceable> and - <replaceable class="parameter">T2</replaceable> can be JOINed tables. - Parenthesis can be used around JOIN clauses to control the order - of JOINs which are otherwise processed left to right. - </para> - - </sect3> - - <sect3> - <title id="aggregates-tutorial">Aggregate Functions</title> - - <para> - <acronym>SQL</acronym> provides aggregate functions such as AVG, - COUNT, SUM, MIN, and MAX. The argument(s) of an aggregate function - are evaluated at each row that satisfies the WHERE - clause, and the aggregate function is calculated over this set - of input values. Normally, an aggregate delivers a single - result for a whole <command>SELECT</command> statement. But if - grouping is specified in the query, then a separate calculation - is done over the rows of each group, and an aggregate result is - delivered per group (see next section). - - <example> - <title id="aggregates-example">Aggregates</title> - - <para> - If we want to know the average cost of all parts in table PART we use - the following query: - -<programlisting> -SELECT AVG(PRICE) AS AVG_PRICE - FROM PART; -</programlisting> - </para> - - <para> - The result is: - -<screen> - AVG_PRICE ------------ - 14.5 -</screen> - </para> - - <para> - If we want to know how many parts are defined in table PART we use - the statement: - -<programlisting> -SELECT COUNT(PNO) - FROM PART; -</programlisting> - - and get: - -<screen> - COUNT -------- - 4 -</screen> - - </para> - </example> - </para> - </sect3> - - <sect3> - <title>Aggregation by Groups</title> - - <para> - <acronym>SQL</acronym> allows one to partition the tuples of a table - into groups. Then the - aggregate functions described above can be applied to the groups — - i.e., the value of the aggregate function is no longer calculated over - all the values of the specified column but over all values of a - group. Thus the aggregate function is evaluated separately for every - group. - </para> - - <para> - The partitioning of the tuples into groups is done by using the - keywords <command>GROUP BY</command> followed by a list of - attributes that define the - groups. If we have - <command>GROUP BY A<subscript>1</subscript>, ⃛, A<subscript>k</subscript></command> - we partition - the relation into groups, such that two tuples are in the same group - if and only if they agree on all the attributes - A<subscript>1</subscript>, ⃛, A<subscript>k</subscript>. - - <example> - <title id="aggregates-groupby">Aggregates</title> - <para> - If we want to know how many parts are sold by every supplier we - formulate the query: - -<programlisting> -SELECT S.SNO, S.SNAME, COUNT(SE.PNO) - FROM SUPPLIER S, SELLS SE - WHERE S.SNO = SE.SNO - GROUP BY S.SNO, S.SNAME; -</programlisting> - - and get: - -<screen> - SNO | SNAME | COUNT ------+-------+------- - 1 | Smith | 2 - 2 | Jones | 1 - 3 | Adams | 2 - 4 | Blake | 3 -</screen> - </para> - - <para> - Now let's have a look of what is happening here. - First the join of the - tables SUPPLIER and SELLS is derived: - -<screen> - S.SNO | S.SNAME | SE.PNO --------+---------+-------- - 1 | Smith | 1 - 1 | Smith | 2 - 2 | Jones | 4 - 3 | Adams | 1 - 3 | Adams | 3 - 4 | Blake | 2 - 4 | Blake | 3 - 4 | Blake | 4 -</screen> - </para> - - <para> - Next we partition the tuples into groups by putting all tuples - together that agree on both attributes S.SNO and S.SNAME: - -<screen> - S.SNO | S.SNAME | SE.PNO --------+---------+-------- - 1 | Smith | 1 - | 2 --------------------------- - 2 | Jones | 4 --------------------------- - 3 | Adams | 1 - | 3 --------------------------- - 4 | Blake | 2 - | 3 - | 4 -</screen> - </para> - - <para> - In our example we got four groups and now we can apply the aggregate - function COUNT to every group leading to the final result of the query - given above. - </para> - </example> - </para> - - <para> - Note that for a query using GROUP BY and aggregate - functions to make sense, the target list can only refer directly to - the attributes being grouped by. Other attributes can only be used - inside the arguments of aggregate functions. Otherwise there would - not be a unique value to associate with the other attributes. - </para> - - <para> - Also observe that it makes no sense to ask for an aggregate of - an aggregate, e.g., AVG(MAX(sno)), because a - <command>SELECT</command> only does one pass of grouping and - aggregation. You can get a result of this kind by using a - temporary table or a sub-SELECT in the FROM clause to do the - first level of aggregation. - </para> - </sect3> - - <sect3> - <title>Having</title> - - <para> - The HAVING clause works much like the WHERE clause and is used to - consider only those groups satisfying the qualification given in the - HAVING clause. Essentially, WHERE filters out unwanted input rows - before grouping and aggregation are done, whereas HAVING filters out - unwanted group rows post-GROUP. Therefore, WHERE cannot refer to the - results of aggregate functions. On the other hand, there's no point - in writing a HAVING condition that doesn't involve an aggregate - function! If your condition doesn't involve aggregates, you might - as well write it in WHERE, and thereby avoid the computation of - aggregates for groups that you're just going to throw away anyway. - - <example> - <title id="having-example">Having</title> - - <para> - If we want only those suppliers selling more than one part we use the - query: - -<programlisting> -SELECT S.SNO, S.SNAME, COUNT(SE.PNO) - FROM SUPPLIER S, SELLS SE - WHERE S.SNO = SE.SNO - GROUP BY S.SNO, S.SNAME - HAVING COUNT(SE.PNO) > 1; -</programlisting> - - and get: - -<screen> - SNO | SNAME | COUNT ------+-------+------- - 1 | Smith | 2 - 3 | Adams | 2 - 4 | Blake | 3 -</screen> - </para> - </example> - </para> - </sect3> - - <sect3> - <title>Subqueries</title> - - <para> - Subqueries in <productname>Postgres-XL</> have restrictions. - You may be warned if some of them cannot be handled. - </para> - - <para> - In the WHERE and HAVING clauses the use of subqueries (subselects) is - allowed in every place where a value is expected. In this case the - value must be derived by evaluating the subquery first. The usage of - subqueries extends the expressive power of - <acronym>SQL</acronym>. - - <example> - <title id="subselect-example">Subselect</title> - - <para> - If we want to know all parts having a greater price than the part - named 'Screw' we use the query: - -<programlisting> -SELECT * - FROM PART - WHERE PRICE > (SELECT PRICE FROM PART - WHERE PNAME='Screw'); -</programlisting> - </para> - - <para> - The result is: - -<screen> - PNO | PNAME | PRICE ------+---------+-------- - 3 | Bolt | 15 - 4 | Cam | 25 -</screen> - </para> - - <para> - When we look at the above query we can see the keyword - <command>SELECT</command> two times. The first one at the - beginning of the query - we will refer to it as outer - <command>SELECT</command> - and the one in the WHERE clause which - begins a nested query - we will refer to it as inner - <command>SELECT</command>. For every tuple of the outer - <command>SELECT</command> the inner <command>SELECT</command> has - to be evaluated. After every evaluation we know the price of the - tuple named 'Screw' and we can check if the price of the actual - tuple is greater. (Actually, in this example the inner query need - only be evaluated once, since it does not depend on the state of - the outer query.) - </para> - - <para> - If we want to know all suppliers that do not sell any part - (e.g., to be able to remove these suppliers from the database) we use: - -<programlisting> -SELECT * - FROM SUPPLIER S - WHERE NOT EXISTS - (SELECT * FROM SELLS SE - WHERE SE.SNO = S.SNO); -</programlisting> - </para> - - <para> - In our example the result will be empty because every supplier - sells at least one part. Note that we use S.SNO from the outer - <command>SELECT</command> within the WHERE clause of the inner - <command>SELECT</command>. Here the subquery must be evaluated - afresh for each tuple from the outer query, i.e., the value for - S.SNO is always taken from the current tuple of the outer - <command>SELECT</command>. - </para> - </example> - </para> - </sect3> - - <sect3> - <title>Subqueries in FROM</title> - - <para> - A somewhat different way of using subqueries is to put them in the - FROM clause. This is a useful feature because a subquery of this - kind can output multiple columns and rows, whereas a subquery used - in an expression must deliver just a single result. It also lets - us get more than one round of grouping/aggregation without resorting - to a temporary table. - - <example> - <title id="subselect-in-from-example">Subselect in FROM</title> - - <para> - If we want to know the highest average part price among all our - suppliers, we cannot write MAX(AVG(PRICE)), but we can write: - -<programlisting> -SELECT MAX(subtable.avgprice) - FROM (SELECT AVG(P.PRICE) AS avgprice - FROM SUPPLIER S, PART P, SELLS SE - WHERE S.SNO = SE.SNO AND - P.PNO = SE.PNO - GROUP BY S.SNO) subtable; -</programlisting> - - The subquery returns one row per supplier (because of its GROUP BY) - and then we aggregate over those rows in the outer query. - </para> - </example> - </para> - </sect3> - - <sect3> - <title>Union, Intersect, Except</title> - - <para> - These operations calculate the union, intersection and set theoretic - difference of the tuples derived by two subqueries. - - <example> - <title id="union-example">Union, Intersect, Except</title> - - <para> - The following query is an example for UNION: - -<programlisting> -SELECT S.SNO, S.SNAME, S.CITY - FROM SUPPLIER S - WHERE S.SNAME = 'Jones' -UNION - SELECT S.SNO, S.SNAME, S.CITY - FROM SUPPLIER S - WHERE S.SNAME = 'Adams'; -</programlisting> - -gives the result: - -<screen> - SNO | SNAME | CITY ------+-------+-------- - 2 | Jones | Paris - 3 | Adams | Vienna -</screen> - </para> - - <para> - Here is an example for INTERSECT: - -<programlisting> -SELECT S.SNO, S.SNAME, S.CITY - FROM SUPPLIER S - WHERE S.SNO > 1 -INTERSECT - SELECT S.SNO, S.SNAME, S.CITY - FROM SUPPLIER S - WHERE S.SNO < 3; -</programlisting> - - gives the result: - -<screen> - SNO | SNAME | CITY ------+-------+-------- - 2 | Jones | Paris -</screen> - - The only tuple returned by both parts of the query is the one having SNO=2. - </para> - - <para> - Finally an example for EXCEPT: - -<programlisting> -SELECT S.SNO, S.SNAME, S.CITY - FROM SUPPLIER S - WHERE S.SNO > 1 -EXCEPT - SELECT S.SNO, S.SNAME, S.CITY - FROM SUPPLIER S - WHERE S.SNO > 3; -</programlisting> - - gives the result: - -<screen> - SNO | SNAME | CITY ------+-------+-------- - 2 | Jones | Paris - 3 | Adams | Vienna -</screen> - </para> - </example> - </para> - </sect3> - </sect2> - - <sect2 id="datadef"> - <title>Data Definition</title> - - <para> - There is a set of commands used for data definition included in the - <acronym>SQL</acronym> language. - </para> - - <sect3 id="create"> - <title id="create-title">Create Table</title> - - <para> - The most fundamental command for data definition is the - one that creates a new relation (a new table). The syntax of the - <command>CREATE TABLE</command> command is: - -<synopsis> -CREATE TABLE <replaceable class="parameter">table_name</replaceable> - (<replaceable class="parameter">name_of_attr_1</replaceable> <replaceable class="parameter">type_of_attr_1</replaceable> - [, <replaceable class="parameter">name_of_attr_2</replaceable> <replaceable class="parameter">type_of_attr_2</replaceable> - [, ...]]); -</synopsis> - - <example> - <title id="table-create">Table Creation</title> - - <para> - To create the tables defined in - <xref linkend="supplier-fig" endterm="supplier-fig"> the - following <acronym>SQL</acronym> statements are used: - -<programlisting> -CREATE TABLE SUPPLIER - (SNO INTEGER, - SNAME VARCHAR(20), - CITY VARCHAR(20)); -</programlisting> - -<programlisting> -CREATE TABLE PART - (PNO INTEGER, - PNAME VARCHAR(20), - PRICE DECIMAL(4 , 2)); -</programlisting> - -<programlisting> -CREATE TABLE SELLS - (SNO INTEGER, - PNO INTEGER); -</programlisting> - </para> - </example> - </para> - </sect3> - - <sect3> - <title>Data Types in <acronym>SQL</acronym></title> - - <para> - The following is a list of some data types that are supported by - <acronym>SQL</acronym>: - - <itemizedlist> - <listitem> - <para> - INTEGER: signed fullword binary integer (31 bits precision). - </para> - </listitem> - - <listitem> - <para> - SMALLINT: signed halfword binary integer (15 bits precision). - </para> - </listitem> - - <listitem> - <para> - DECIMAL (<replaceable class="parameter">p</replaceable>[,<replaceable class="parameter">q</replaceable>]): - signed packed decimal number of up to - <replaceable class="parameter">p</replaceable> - digits, with - <replaceable class="parameter">q</replaceable> - digits to the right of the decimal point. - If <replaceable class="parameter">q</replaceable> - is omitted it is assumed to be 0. - </para> - </listitem> - - <listitem> - <para> - FLOAT: signed doubleword floating point number. - </para> - </listitem> - - <listitem> - <para> - VARCHAR(<replaceable class="parameter">n</replaceable>): - varying length character string of maximum length - <replaceable class="parameter">n</replaceable>. - </para> - </listitem> - - <listitem> - <para> - CHAR(<replaceable class="parameter">n</replaceable>): - fixed length character string of length - <replaceable class="parameter">n</replaceable>. - </para> - </listitem> - - </itemizedlist> - </para> - </sect3> - - <sect3> - <title>Create Index</title> - - <para> - Indexes are used to speed up access to a relation. If a relation <classname>R</classname> - has an index on attribute <classname>A</classname> then we can - retrieve all tuples <replaceable>t</replaceable> - having - <replaceable>t</replaceable>(<classname>A</classname>) = <replaceable>a</replaceable> - in time roughly proportional to the number of such - tuples <replaceable>t</replaceable> - rather than in time proportional to the size of <classname>R</classname>. - </para> - - <para> - To create an index in <acronym>SQL</acronym> - the <command>CREATE INDEX</command> command is used. The syntax is: - -<programlisting> -CREATE INDEX <replaceable class="parameter">index_name</replaceable> - ON <replaceable class="parameter">table_name</replaceable> ( <replaceable class="parameter">name_of_attribute</replaceable> ); -</programlisting> - </para> - - <para> - <example> - <title id="index-create">Create Index</title> - - <para> - To create an index named I on attribute SNAME of relation SUPPLIER - we use the following statement: - -<programlisting> -CREATE INDEX I ON SUPPLIER (SNAME); -</programlisting> - </para> - - <para> - The created index is maintained automatically, i.e., whenever a new - tuple is inserted into the relation SUPPLIER the index I is - adapted. Note that the only changes a user can perceive when an - index is present are increased speed for <command>SELECT</command> - and decreases in speed of updates. - </para> - </example> - </para> - </sect3> - - <sect3> - <title>Create View</title> - - <para> - A view can be regarded as a <firstterm>virtual table</firstterm>, - i.e., a table that - does not <emphasis>physically</emphasis> exist in the database - but looks to the user - as if it does. By contrast, when we talk of a - <firstterm>base table</firstterm> there is - really a physically stored counterpart of each row of the table - somewhere in the physical storage. - </para> - - <para> - Views do not have their own, physically separate, distinguishable - stored data. Instead, the system stores the definition of the - view (i.e., the rules about how to access physically stored base - tables in order to materialize the view) somewhere in the system - catalogs (see - <xref linkend="tutorial-catalogs-title" endterm="tutorial-catalogs-title">). For a - discussion on different techniques to implement views refer to -<!-- - section - <xref linkend="view-impl" endterm="view-impl">. ---> - <citetitle>SIM98</citetitle>. - </para> - - <para> - In <acronym>SQL</acronym> the <command>CREATE VIEW</command> - command is used to define a view. The syntax - is: - -<programlisting> -CREATE VIEW <replaceable class="parameter">view_name</replaceable> - AS <replaceable class="parameter">select_stmt</replaceable> -</programlisting> - - where <replaceable class="parameter">select_stmt</replaceable> - is a valid select statement as defined - in <xref linkend="select-title" endterm="select-title">. - Note that <replaceable class="parameter">select_stmt</replaceable> is - not executed when the view is created. It is just stored in the - <firstterm>system catalogs</firstterm> - and is executed whenever a query against the view is made. - </para> - - <para> - Let the following view definition be given (we use - the tables from - <xref linkend="supplier-fig" endterm="supplier-fig"> again): - -<programlisting> -CREATE VIEW London_Suppliers - AS SELECT S.SNAME, P.PNAME - FROM SUPPLIER S, PART P, SELLS SE - WHERE S.SNO = SE.SNO AND - P.PNO = SE.PNO AND - S.CITY = 'London'; -</programlisting> - </para> - - <para> - Now we can use this <firstterm>virtual relation</firstterm> - <classname>London_Suppliers</classname> as - if it were another base table: - -<programlisting> -SELECT * FROM London_Suppliers - WHERE PNAME = 'Screw'; -</programlisting> - - which will return the following table: - -<screen> - SNAME | PNAME --------+------- - Smith | Screw -</screen> - </para> - - <para> - To calculate this result the database system has to do a - <emphasis>hidden</emphasis> - access to the base tables SUPPLIER, SELLS and PART first. It - does so by executing the query given in the view definition against - those base tables. After that the additional qualifications - (given in the - query against the view) can be applied to obtain the resulting - table. - </para> - </sect3> - - <sect3> - <title>Drop Table, Drop Index, Drop View</title> - - <para> - To destroy a table (including all tuples stored in that table) the - <command>DROP TABLE</command> command is used: - -<programlisting> -DROP TABLE <replaceable class="parameter">table_name</replaceable>; -</programlisting> - </para> - - <para> - To destroy the SUPPLIER table use the following statement: - -<programlisting> -DROP TABLE SUPPLIER; -</programlisting> - </para> - - <para> - The <command>DROP INDEX</command> command is used to destroy an index: - -<programlisting> -DROP INDEX <replaceable class="parameter">index_name</replaceable>; -</programlisting> - </para> - - <para> - Finally to destroy a given view use the command <command>DROP - VIEW</command>: - -<programlisting> -DROP VIEW <replaceable class="parameter">view_name</replaceable>; -</programlisting> - </para> - </sect3> - </sect2> - - <sect2> - <title>Data Manipulation</title> - - <sect3> - <title>Insert Into</title> - - <para> - Once a table is created (see - <xref linkend="create-title" endterm="create-title">), it can be filled - with tuples using the command <command>INSERT INTO</command>. - The syntax is: - -<programlisting> -INSERT INTO <replaceable class="parameter">table_name</replaceable> (<replaceable class="parameter">name_of_attr_1</replaceable> - [, <replaceable class="parameter">name_of_attr_2</replaceable> [, ...]]) - VALUES (<replaceable class="parameter">val_attr_1</replaceable> [, <replaceable class="parameter">val_attr_2</replaceable> [, ...]]); -</programlisting> - </para> - - <para> - To insert the first tuple into the relation SUPPLIER (from - <xref linkend="supplier-fig" endterm="supplier-fig">) we use the - following statement: - -<programlisting> -INSERT INTO SUPPLIER (SNO, SNAME, CITY) - VALUES (1, 'Smith', 'London'); -</programlisting> - </para> - - <para> - To insert the first tuple into the relation SELLS we use: - -<programlisting> -INSERT INTO SELLS (SNO, PNO) - VALUES (1, 1); -</programlisting> - </para> - </sect3> - - <sect3> - <title>Update</title> - - <para> - To change one or more attribute values of tuples in a relation the - <command>UPDATE</command> command is used. The syntax is: - -<programlisting> -UPDATE <replaceable class="parameter">table_name</replaceable> - SET <replaceable class="parameter">name_of_attr_1</replaceable> = <replaceable class="parameter">value_1</replaceable> - [, ... [, <replaceable class="parameter">name_of_attr_k</replaceable> = <replaceable class="parameter">value_k</replaceable>]] - WHERE <replaceable class="parameter">condition</replaceable>; -</programlisting> - </para> - - <para> - To change the value of attribute PRICE of the part 'Screw' in the - relation PART we use: - -<programlisting> -UPDATE PART - SET PRICE = 15 - WHERE PNAME = 'Screw'; -</programlisting> - </para> - - <para> - The new value of attribute PRICE of the tuple whose name is 'Screw' is - now 15. - </para> - </sect3> - - <sect3> - <title>Delete</title> - - <para> - To delete a tuple from a particular table use the command DELETE - FROM. The syntax is: - -<programlisting> -DELETE FROM <replaceable class="parameter">table_name</replaceable> - WHERE <replaceable class="parameter">condition</replaceable>; -</programlisting> - </para> - - <para> - To delete the supplier called 'Smith' of the table SUPPLIER the - following statement is used: - -<programlisting> -DELETE FROM SUPPLIER - WHERE SNAME = 'Smith'; -</programlisting> - </para> - </sect3> - </sect2> - - <sect2 id="tutorial-catalogs"> - <title id="tutorial-catalogs-title">System Catalogs</title> - - <para> - In every <acronym>SQL</acronym> database system - <firstterm>system catalogs</firstterm> are used to keep - track of which tables, views indexes etc. are defined in the - database. These system catalogs can be queried as if they were normal - relations. For example there is one catalog used for the definition of - views. This catalog stores the query from the view definition. Whenever - a query against a view is made, the system first gets the - <firstterm>view definition query</firstterm> out of the catalog - and materializes the view - before proceeding with the user query (see -<!-- - section - <xref linkend="view-impl" endterm="view-impl">. - <citetitle>SIM98</citetitle> ---> - <xref linkend="SIM98" endterm="SIM98"> - for a more detailed - description). For more information about system catalogs refer to - <xref linkend="DATE04" endterm="DATE04">. - </para> - </sect2> - - <sect2> - <title>Embedded <acronym>SQL</acronym></title> - - <para> - In this section we will sketch how <acronym>SQL</acronym> can be - embedded into a host language (e.g., <literal>C</literal>). - There are two main reasons why we want to use <acronym>SQL</acronym> - from a host language: - - <itemizedlist> - <listitem> - <para> - There are queries that cannot be formulated using pure <acronym>SQL</acronym> - (i.e., recursive queries). To be able to perform such queries we need a - host language with a greater expressive power than - <acronym>SQL</acronym>. - </para> - </listitem> - - <listitem> - <para> - We simply want to access a database from some application that - is written in the host language (e.g., a ticket reservation system - with a graphical user interface is written in C and the information - about which tickets are still left is stored in a database that can be - accessed using embedded <acronym>SQL</acronym>). - </para> - </listitem> - </itemizedlist> - </para> - - <para> - A program using embedded <acronym>SQL</acronym> - in a host language consists of statements - of the host language and of - <firstterm>embedded <acronym>SQL</acronym></firstterm> - (<acronym>ESQL</acronym>) statements. Every <acronym>ESQL</acronym> - statement begins with the keywords <command>EXEC SQL</command>. - The <acronym>ESQL</acronym> statements are - transformed to statements of the host language - by a <firstterm>precompiler</firstterm> - (which usually inserts - calls to library routines that perform the various <acronym>SQL</acronym> - commands). - </para> - - <para> - When we look at the examples throughout - <xref linkend="select-title" endterm="select-title"> we - realize that the result of the queries is very often a set of - tuples. Most host languages are not designed to operate on sets so we - need a mechanism to access every single tuple of the set of tuples - returned by a SELECT statement. This mechanism can be provided by - declaring a <firstterm>cursor</firstterm>. - After that we can use the <command>FETCH</command> command to - retrieve a tuple and set the cursor to the next tuple. - </para> - - <para> - For a detailed discussion on embedded <acronym>SQL</acronym> - refer to - <xref linkend="DATE97" endterm="DATE97">, - <xref linkend="DATE04" endterm="DATE04">, - or - <xref linkend="ULL88" endterm="ULL88">. - </para> - </sect2> - </sect1> - </chapter> diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml index 1b812bd0a9..a156693ec8 100644 --- a/doc/src/sgml/storage.sgml +++ b/doc/src/sgml/storage.sgml @@ -61,6 +61,12 @@ Item </row> <row> + <entry><filename>current_logfiles</></entry> + <entry>File recording the log file(s) currently written to by the logging + collector</entry> +</row> + +<row> <entry><filename>global</></entry> <entry>Subdirectory containing cluster-wide tables, such as <structname>pg_database</></entry> @@ -72,11 +78,6 @@ Item </row> <row> - <entry><filename>pg_clog</></entry> - <entry>Subdirectory containing transaction commit status data</entry> -</row> - -<row> <entry><filename>pg_dynshmem</></entry> <entry>Subdirectory containing files used by the dynamic shared memory subsystem</entry> @@ -141,11 +142,16 @@ Item </row> <row> - <entry><filename>pg_xlog</></entry> + <entry><filename>pg_wal</></entry> <entry>Subdirectory containing WAL (Write Ahead Log) files</entry> </row> <row> + <entry><filename>pg_xact</></entry> + <entry>Subdirectory containing transaction commit status data</entry> +</row> + +<row> <entry><filename>postgresql.auto.conf</></entry> <entry>A file used for storing configuration parameters that are set by <command>ALTER SYSTEM</command></entry> @@ -474,7 +480,7 @@ for storing <acronym>TOAST</>-able columns on disk: Each <acronym>TOAST</>-able data type specifies a default strategy for columns of that data type, but the strategy for a given table column can be altered -with <command>ALTER TABLE SET STORAGE</>. +with <link linkend="sql-altertable"><command>ALTER TABLE ... SET STORAGE</></link>. </para> <para> @@ -810,7 +816,7 @@ data. Empty in ordinary tables.</entry> <entry>pd_lsn</entry> <entry>PageXLogRecPtr</entry> <entry>8 bytes</entry> - <entry>LSN: next byte after last byte of xlog record for last change + <entry>LSN: next byte after last byte of WAL record for last change to this page</entry> </row> <row> diff --git a/doc/src/sgml/stylesheet-common.xsl b/doc/src/sgml/stylesheet-common.xsl index de3637624a..658a5ac5e1 100644 --- a/doc/src/sgml/stylesheet-common.xsl +++ b/doc/src/sgml/stylesheet-common.xsl @@ -7,11 +7,10 @@ all output formats (HTML, HTML Help, XSL-FO, etc.). --> +<xsl:include href="stylesheet-speedup-common.xsl" /> <!-- Parameters --> -<xsl:param name="pg.fast" select="'0'"/> - <!-- <xsl:param name="draft.mode"> <xsl:choose> @@ -31,14 +30,16 @@ <xsl:param name="callout.graphics" select="'0'"></xsl:param> <xsl:param name="toc.section.depth">2</xsl:param> <xsl:param name="linenumbering.extension" select="'0'"></xsl:param> -<xsl:param name="generate.index" select="1 - $pg.fast"></xsl:param> -<xsl:param name="section.autolabel" select="1 - $pg.fast"></xsl:param> -<xsl:param name="section.label.includes.component.label" select="1 - $pg.fast"></xsl:param> +<xsl:param name="section.autolabel" select="1"></xsl:param> +<xsl:param name="section.label.includes.component.label" select="1"></xsl:param> +<xsl:param name="refentry.generate.name" select="0"></xsl:param> +<xsl:param name="refentry.generate.title" select="1"></xsl:param> <xsl:param name="refentry.xref.manvolnum" select="0"/> <xsl:param name="formal.procedures" select="0"></xsl:param> <xsl:param name="punct.honorific" select="''"></xsl:param> <xsl:param name="variablelist.term.break.after">1</xsl:param> <xsl:param name="variablelist.term.separator"></xsl:param> +<xsl:param name="xref.with.number.and.title" select="0"></xsl:param> <!-- Change display of some elements --> @@ -79,7 +80,9 @@ <!-- Special support for Tcl synopses --> <xsl:template match="optional[@role='tcl']"> - ?<xsl:call-template name="inline.charseq"/>? + <xsl:text>?</xsl:text> + <xsl:call-template name="inline.charseq"/> + <xsl:text>?</xsl:text> </xsl:template> </xsl:stylesheet> diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xsl index 434e69d8e3..7a0fbe9564 100644 --- a/doc/src/sgml/stylesheet-fo.xsl +++ b/doc/src/sgml/stylesheet-fo.xsl @@ -18,12 +18,51 @@ <xsl:attribute name="wrap-option">wrap</xsl:attribute> </xsl:attribute-set> +<xsl:attribute-set name="nongraphical.admonition.properties"> + <xsl:attribute name="border-style">solid</xsl:attribute> + <xsl:attribute name="border-width">1pt</xsl:attribute> + <xsl:attribute name="border-color">black</xsl:attribute> + <xsl:attribute name="padding-start">12pt</xsl:attribute> + <xsl:attribute name="padding-end">12pt</xsl:attribute> + <xsl:attribute name="padding-top">6pt</xsl:attribute> + <xsl:attribute name="padding-bottom">6pt</xsl:attribute> +</xsl:attribute-set> + +<xsl:attribute-set name="admonition.title.properties"> + <xsl:attribute name="text-align">center</xsl:attribute> +</xsl:attribute-set> + +<!-- fix missing space after vertical simplelist + https://github.com/docbook/xslt10-stylesheets/issues/31 --> +<xsl:attribute-set name="normal.para.spacing"> + <xsl:attribute name="space-after.optimum">1em</xsl:attribute> + <xsl:attribute name="space-after.minimum">0.8em</xsl:attribute> + <xsl:attribute name="space-after.maximum">1.2em</xsl:attribute> +</xsl:attribute-set> + <!-- Change display of some elements --> <xsl:template match="command"> <xsl:call-template name="inline.monoseq"/> </xsl:template> +<xsl:template match="confgroup" mode="bibliography.mode"> + <fo:inline> + <xsl:apply-templates select="conftitle/text()" mode="bibliography.mode"/> + <xsl:text>, </xsl:text> + <xsl:apply-templates select="confdates/text()" mode="bibliography.mode"/> + <xsl:value-of select="$biblioentry.item.separator"/> + </fo:inline> +</xsl:template> + +<xsl:template match="isbn" mode="bibliography.mode"> + <fo:inline> + <xsl:text>ISBN </xsl:text> + <xsl:apply-templates mode="bibliography.mode"/> + <xsl:value-of select="$biblioentry.item.separator"/> + </fo:inline> +</xsl:template> + <!-- bug fix from <https://sourceforge.net/p/docbook/bugs/1360/#831b> --> <xsl:template match="varlistentry/term" mode="xref-to"> diff --git a/doc/src/sgml/stylesheet-html-common.xsl b/doc/src/sgml/stylesheet-html-common.xsl new file mode 100644 index 0000000000..72fac1e806 --- /dev/null +++ b/doc/src/sgml/stylesheet-html-common.xsl @@ -0,0 +1,266 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE xsl:stylesheet [ +<!ENTITY % common.entities SYSTEM "http://docbook.sourceforge.net/release/xsl/current/common/entities.ent"> +%common.entities; +]> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- + This file contains XSLT stylesheet customizations that are common to + all HTML output variants (chunked and single-page). + --> + +<!-- Parameters --> +<xsl:param name="make.valid.html" select="1"></xsl:param> +<xsl:param name="generate.id.attributes" select="1"></xsl:param> +<xsl:param name="link.mailto.url">[email protected]</xsl:param> +<xsl:param name="toc.max.depth">2</xsl:param> + + +<!-- Change display of some elements --> + +<xsl:template match="command"> + <xsl:call-template name="inline.monoseq"/> +</xsl:template> + +<xsl:template match="confgroup" mode="bibliography.mode"> + <span> + <xsl:call-template name="common.html.attributes"/> + <xsl:call-template name="id.attribute"/> + <xsl:apply-templates select="conftitle/text()" mode="bibliography.mode"/> + <xsl:text>, </xsl:text> + <xsl:apply-templates select="confdates/text()" mode="bibliography.mode"/> + <xsl:copy-of select="$biblioentry.item.separator"/> + </span> +</xsl:template> + +<xsl:template match="isbn" mode="bibliography.mode"> + <span> + <xsl:call-template name="common.html.attributes"/> + <xsl:call-template name="id.attribute"/> + <xsl:text>ISBN </xsl:text> + <xsl:apply-templates mode="bibliography.mode"/> + <xsl:copy-of select="$biblioentry.item.separator"/> + </span> +</xsl:template> + + +<!-- table of contents configuration --> + +<xsl:param name="generate.toc"> +appendix toc,title +article/appendix nop +article toc,title +book toc,title +chapter toc,title +part toc,title +preface toc,title +qandadiv toc +qandaset toc +reference toc,title +sect1 toc +sect2 toc +sect3 toc +sect4 toc +sect5 toc +section toc +set toc,title +</xsl:param> + +<xsl:param name="generate.section.toc.level" select="1"></xsl:param> + +<!-- include refentry under sect1 in tocs --> +<xsl:template match="sect1" mode="toc"> + <xsl:param name="toc-context" select="."/> + <xsl:call-template name="subtoc"> + <xsl:with-param name="toc-context" select="$toc-context"/> + <xsl:with-param name="nodes" select="sect2|refentry + |bridgehead[$bridgehead.in.toc != 0]"/> + </xsl:call-template> +</xsl:template> + + +<!-- Put index "quicklinks" (A | B | C | ...) at the top of the bookindex page. --> + +<!-- from html/autoidx.xsl --> + +<xsl:template name="generate-basic-index"> + <xsl:param name="scope" select="NOTANODE"/> + + <xsl:variable name="role"> + <xsl:if test="$index.on.role != 0"> + <xsl:value-of select="@role"/> + </xsl:if> + </xsl:variable> + + <xsl:variable name="type"> + <xsl:if test="$index.on.type != 0"> + <xsl:value-of select="@type"/> + </xsl:if> + </xsl:variable> + + <xsl:variable name="terms" + select="//indexterm + [count(.|key('letter', + translate(substring(&primary;, 1, 1), + &lowercase;, + &uppercase;)) + [&scope;][1]) = 1 + and not(@class = 'endofrange')]"/> + + <xsl:variable name="alphabetical" + select="$terms[contains(concat(&lowercase;, &uppercase;), + substring(&primary;, 1, 1))]"/> + + <xsl:variable name="others" select="$terms[not(contains(concat(&lowercase;, + &uppercase;), + substring(&primary;, 1, 1)))]"/> + + <div class="index"> + <!-- pgsql-docs: begin added stuff --> + <p class="indexdiv-quicklinks"> + <a href="#indexdiv-Symbols"> + <xsl:call-template name="gentext"> + <xsl:with-param name="key" select="'index symbols'"/> + </xsl:call-template> + </a> + <xsl:apply-templates select="$alphabetical[count(.|key('letter', + translate(substring(&primary;, 1, 1), + &lowercase;,&uppercase;))[&scope;][1]) = 1]" + mode="index-div-quicklinks"> + <xsl:with-param name="position" select="position()"/> + <xsl:with-param name="scope" select="$scope"/> + <xsl:with-param name="role" select="$role"/> + <xsl:with-param name="type" select="$type"/> + <xsl:sort select="translate(&primary;, &lowercase;, &uppercase;)"/> + </xsl:apply-templates> + </p> + <!-- pgsql-docs: end added stuff --> + + <xsl:if test="$others"> + <xsl:choose> + <xsl:when test="normalize-space($type) != '' and + $others[@type = $type][count(.|key('primary', &primary;)[&scope;][1]) = 1]"> + <!-- pgsql-docs: added id attribute here for linking to it --> + <div class="indexdiv" id="indexdiv-Symbols"> + <h3> + <xsl:call-template name="gentext"> + <xsl:with-param name="key" select="'index symbols'"/> + </xsl:call-template> + </h3> + <dl> + <xsl:apply-templates select="$others[count(.|key('primary', &primary;)[&scope;][1]) = 1]" + mode="index-symbol-div"> + <xsl:with-param name="position" select="position()"/> + <xsl:with-param name="scope" select="$scope"/> + <xsl:with-param name="role" select="$role"/> + <xsl:with-param name="type" select="$type"/> + <xsl:sort select="translate(&primary;, &lowercase;, &uppercase;)"/> + </xsl:apply-templates> + </dl> + </div> + </xsl:when> + <xsl:when test="normalize-space($type) != ''"> + <!-- Output nothing, as there isn't a match for $other using this $type --> + </xsl:when> + <xsl:otherwise> + <!-- pgsql-docs: added id attribute here for linking to it --> + <div class="indexdiv" id="indexdiv-Symbols"> + <h3> + <xsl:call-template name="gentext"> + <xsl:with-param name="key" select="'index symbols'"/> + </xsl:call-template> + </h3> + <dl> + <xsl:apply-templates select="$others[count(.|key('primary', + &primary;)[&scope;][1]) = 1]" + mode="index-symbol-div"> + <xsl:with-param name="position" select="position()"/> + <xsl:with-param name="scope" select="$scope"/> + <xsl:with-param name="role" select="$role"/> + <xsl:with-param name="type" select="$type"/> + <xsl:sort select="translate(&primary;, &lowercase;, &uppercase;)"/> + </xsl:apply-templates> + </dl> + </div> + </xsl:otherwise> + </xsl:choose> + </xsl:if> + + <xsl:apply-templates select="$alphabetical[count(.|key('letter', + translate(substring(&primary;, 1, 1), + &lowercase;,&uppercase;))[&scope;][1]) = 1]" + mode="index-div-basic"> + <xsl:with-param name="position" select="position()"/> + <xsl:with-param name="scope" select="$scope"/> + <xsl:with-param name="role" select="$role"/> + <xsl:with-param name="type" select="$type"/> + <xsl:sort select="translate(&primary;, &lowercase;, &uppercase;)"/> + </xsl:apply-templates> + </div> +</xsl:template> + +<xsl:template match="indexterm" mode="index-div-basic"> + <xsl:param name="scope" select="."/> + <xsl:param name="role" select="''"/> + <xsl:param name="type" select="''"/> + + <xsl:variable name="key" + select="translate(substring(&primary;, 1, 1), + &lowercase;,&uppercase;)"/> + + <xsl:if test="key('letter', $key)[&scope;] + [count(.|key('primary', &primary;)[&scope;][1]) = 1]"> + <div class="indexdiv"> + <!-- pgsql-docs: added id attribute here for linking to it --> + <xsl:attribute name="id"> + <xsl:value-of select="concat('indexdiv-', $key)"/> + </xsl:attribute> + + <xsl:if test="contains(concat(&lowercase;, &uppercase;), $key)"> + <h3> + <xsl:value-of select="translate($key, &lowercase;, &uppercase;)"/> + </h3> + </xsl:if> + <dl> + <xsl:apply-templates select="key('letter', $key)[&scope;] + [count(.|key('primary', &primary;) + [&scope;][1])=1]" + mode="index-primary"> + <xsl:with-param name="position" select="position()"/> + <xsl:with-param name="scope" select="$scope"/> + <xsl:with-param name="role" select="$role"/> + <xsl:with-param name="type" select="$type"/> + <xsl:sort select="translate(&primary;, &lowercase;, &uppercase;)"/> + </xsl:apply-templates> + </dl> + </div> + </xsl:if> +</xsl:template> + +<!-- pgsql-docs --> +<xsl:template match="indexterm" mode="index-div-quicklinks"> + <xsl:param name="scope" select="."/> + <xsl:param name="role" select="''"/> + <xsl:param name="type" select="''"/> + + <xsl:variable name="key" + select="translate(substring(&primary;, 1, 1), + &lowercase;,&uppercase;)"/> + + <xsl:if test="key('letter', $key)[&scope;] + [count(.|key('primary', &primary;)[&scope;][1]) = 1]"> + <xsl:if test="contains(concat(&lowercase;, &uppercase;), $key)"> + | + <a> + <xsl:attribute name="href"> + <xsl:value-of select="concat('#indexdiv-', $key)"/> + </xsl:attribute> + <xsl:value-of select="translate($key, &lowercase;, &uppercase;)"/> + </a> + </xsl:if> + </xsl:if> +</xsl:template> + +</xsl:stylesheet> diff --git a/doc/src/sgml/stylesheet-html-nochunk.xsl b/doc/src/sgml/stylesheet-html-nochunk.xsl new file mode 100644 index 0000000000..ffd2012e91 --- /dev/null +++ b/doc/src/sgml/stylesheet-html-nochunk.xsl @@ -0,0 +1,12 @@ +<?xml version='1.0'?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version='1.0' + xmlns="http://www.w3.org/TR/xhtml1/transitional" + exclude-result-prefixes="#default"> + +<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"/> +<xsl:include href="stylesheet-common.xsl" /> +<xsl:include href="stylesheet-html-common.xsl" /> +<xsl:include href="stylesheet-speedup-xhtml.xsl" /> + +</xsl:stylesheet> diff --git a/doc/src/sgml/stylesheet-speedup-common.xsl b/doc/src/sgml/stylesheet-speedup-common.xsl new file mode 100644 index 0000000000..e3fb582a1c --- /dev/null +++ b/doc/src/sgml/stylesheet-speedup-common.xsl @@ -0,0 +1,100 @@ +<?xml version="1.0" encoding="utf-8"?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version='1.0'> + +<!-- Performance-optimized versions of some upstream templates from common/ + directory --> + +<!-- from common/labels.xsl --> + +<xsl:template match="chapter" mode="label.markup"> + <xsl:choose> + <xsl:when test="@label"> + <xsl:value-of select="@label"/> + </xsl:when> + <xsl:when test="string($chapter.autolabel) != 0"> + <xsl:if test="$component.label.includes.part.label != 0 and + ancestor::part"> + <xsl:variable name="part.label"> + <xsl:apply-templates select="ancestor::part" + mode="label.markup"/> + </xsl:variable> + <xsl:if test="$part.label != ''"> + <xsl:value-of select="$part.label"/> + <xsl:apply-templates select="ancestor::part" + mode="intralabel.punctuation"> + <xsl:with-param name="object" select="."/> + </xsl:apply-templates> + </xsl:if> + </xsl:if> + <xsl:variable name="format"> + <xsl:call-template name="autolabel.format"> + <xsl:with-param name="format" select="$chapter.autolabel"/> + </xsl:call-template> + </xsl:variable> + <xsl:choose> + <xsl:when test="$label.from.part != 0 and ancestor::part"> + <xsl:number from="part" count="chapter" format="{$format}" level="any"/> + </xsl:when> + <xsl:otherwise> + <!-- Optimization for pgsql-docs: When counting to get label for + this chapter, preceding chapters can only be our siblings or + children of a preceding part, so only count those instead of + scanning the entire node tree. --> + <!-- <xsl:number from="book" count="chapter" format="{$format}" level="any"/> --> + <xsl:number value="count(../preceding-sibling::part/chapter) + count(preceding-sibling::chapter) + 1" format="{$format}"/> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + </xsl:choose> +</xsl:template> + +<xsl:template match="appendix" mode="label.markup"> + <xsl:choose> + <xsl:when test="@label"> + <xsl:value-of select="@label"/> + </xsl:when> + <xsl:when test="string($appendix.autolabel) != 0"> + <xsl:if test="$component.label.includes.part.label != 0 and + ancestor::part"> + <xsl:variable name="part.label"> + <xsl:apply-templates select="ancestor::part" + mode="label.markup"/> + </xsl:variable> + <xsl:if test="$part.label != ''"> + <xsl:value-of select="$part.label"/> + <xsl:apply-templates select="ancestor::part" + mode="intralabel.punctuation"> + <xsl:with-param name="object" select="."/> + </xsl:apply-templates> + </xsl:if> + </xsl:if> + <xsl:variable name="format"> + <xsl:call-template name="autolabel.format"> + <xsl:with-param name="format" select="$appendix.autolabel"/> + </xsl:call-template> + </xsl:variable> + <xsl:choose> + <xsl:when test="$label.from.part != 0 and ancestor::part"> + <xsl:number from="part" count="appendix" format="{$format}" level="any"/> + </xsl:when> + <xsl:otherwise> + <!-- Optimization for pgsql-docs: When counting to get label for + this appendix, preceding appendixes can only be our siblings or + children of a preceding part, so only count those instead of + scanning the entire node tree. --> + <!-- <xsl:number from="book|article" count="appendix" format="{$format}" level="any"/> --> + <xsl:number value="count(../preceding-sibling::part/appendix) + count(preceding-sibling::appendix) + 1" format="{$format}"/> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + </xsl:choose> +</xsl:template> + +<!-- from common/l10n.xsl --> + +<!-- Just hardcode the language for the whole document, to make it faster. --> + +<xsl:template name="l10n.language">en</xsl:template> + +</xsl:stylesheet> diff --git a/doc/src/sgml/stylesheet-speedup-xhtml.xsl b/doc/src/sgml/stylesheet-speedup-xhtml.xsl new file mode 100644 index 0000000000..da0f2b5a97 --- /dev/null +++ b/doc/src/sgml/stylesheet-speedup-xhtml.xsl @@ -0,0 +1,345 @@ +<?xml version="1.0" encoding="utf-8"?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns="http://www.w3.org/1999/xhtml" + version='1.0'> + +<!-- Performance-optimized versions of some upstream templates from xhtml/ + directory --> + +<!-- from xhtml/autoidx.xsl --> + +<xsl:template match="indexterm" mode="reference"> + <xsl:param name="scope" select="."/> + <xsl:param name="role" select="''"/> + <xsl:param name="type" select="''"/> + <xsl:param name="position"/> + <xsl:param name="separator" select="''"/> + + <xsl:variable name="term.separator"> + <xsl:call-template name="index.separator"> + <xsl:with-param name="key" select="'index.term.separator'"/> + </xsl:call-template> + </xsl:variable> + + <xsl:variable name="number.separator"> + <xsl:call-template name="index.separator"> + <xsl:with-param name="key" select="'index.number.separator'"/> + </xsl:call-template> + </xsl:variable> + + <xsl:variable name="range.separator"> + <xsl:call-template name="index.separator"> + <xsl:with-param name="key" select="'index.range.separator'"/> + </xsl:call-template> + </xsl:variable> + + <xsl:choose> + <xsl:when test="$separator != ''"> + <xsl:value-of select="$separator"/> + </xsl:when> + <xsl:when test="$position = 1"> + <xsl:value-of select="$term.separator"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$number.separator"/> + </xsl:otherwise> + </xsl:choose> + + <xsl:choose> + <xsl:when test="@zone and string(@zone)"> + <xsl:call-template name="reference"> + <xsl:with-param name="zones" select="normalize-space(@zone)"/> + <xsl:with-param name="position" select="position()"/> + <xsl:with-param name="scope" select="$scope"/> + <xsl:with-param name="role" select="$role"/> + <xsl:with-param name="type" select="$type"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <a> + <xsl:apply-templates select="." mode="class.attribute"/> + <xsl:variable name="title"> + <xsl:choose> + <xsl:when test="$index.prefer.titleabbrev != 0"> + <xsl:apply-templates select="(ancestor-or-self::set|ancestor-or-self::book|ancestor-or-self::part|ancestor-or-self::reference|ancestor-or-self::partintro|ancestor-or-self::chapter|ancestor-or-self::appendix|ancestor-or-self::preface|ancestor-or-self::article|ancestor-or-self::section|ancestor-or-self::sect1|ancestor-or-self::sect2|ancestor-or-self::sect3|ancestor-or-self::sect4|ancestor-or-self::sect5|ancestor-or-self::refentry|ancestor-or-self::refsect1|ancestor-or-self::refsect2|ancestor-or-self::refsect3|ancestor-or-self::simplesect|ancestor-or-self::bibliography|ancestor-or-self::glossary|ancestor-or-self::index|ancestor-or-self::webpage|ancestor-or-self::topic)[last()]" mode="titleabbrev.markup"/> + </xsl:when> + <xsl:otherwise> + <xsl:apply-templates select="(ancestor-or-self::set|ancestor-or-self::book|ancestor-or-self::part|ancestor-or-self::reference|ancestor-or-self::partintro|ancestor-or-self::chapter|ancestor-or-self::appendix|ancestor-or-self::preface|ancestor-or-self::article|ancestor-or-self::section|ancestor-or-self::sect1|ancestor-or-self::sect2|ancestor-or-self::sect3|ancestor-or-self::sect4|ancestor-or-self::sect5|ancestor-or-self::refentry|ancestor-or-self::refsect1|ancestor-or-self::refsect2|ancestor-or-self::refsect3|ancestor-or-self::simplesect|ancestor-or-self::bibliography|ancestor-or-self::glossary|ancestor-or-self::index|ancestor-or-self::webpage|ancestor-or-self::topic)[last()]" mode="title.markup"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:attribute name="href"> + <xsl:choose> + <xsl:when test="$index.links.to.section = 1"> + <xsl:call-template name="href.target"> + <xsl:with-param name="object" select="(ancestor-or-self::set|ancestor-or-self::book|ancestor-or-self::part|ancestor-or-self::reference|ancestor-or-self::partintro|ancestor-or-self::chapter|ancestor-or-self::appendix|ancestor-or-self::preface|ancestor-or-self::article|ancestor-or-self::section|ancestor-or-self::sect1|ancestor-or-self::sect2|ancestor-or-self::sect3|ancestor-or-self::sect4|ancestor-or-self::sect5|ancestor-or-self::refentry|ancestor-or-self::refsect1|ancestor-or-self::refsect2|ancestor-or-self::refsect3|ancestor-or-self::simplesect|ancestor-or-self::bibliography|ancestor-or-self::glossary|ancestor-or-self::index|ancestor-or-self::webpage|ancestor-or-self::topic)[last()]"/> + <!-- Optimization for pgsql-docs: We only have an index as a + child of book, so look that up directly instead of + scanning the entire node tree. Also, don't look for + setindex. --> + <!-- <xsl:with-param name="context" select="(//index[count(ancestor::node()|$scope) = count(ancestor::node()) and ($role = @role or $type = @type or (string-length($role) = 0 and string-length($type) = 0))] | //setindex[count(ancestor::node()|$scope) = count(ancestor::node()) and ($role = @role or $type = @type or (string-length($role) = 0 and string-length($type) = 0))])[1]"/> --> + <xsl:with-param name="context" select="(/book/index[count(ancestor::node()|$scope) = count(ancestor::node()) and ($role = @role or $type = @type or (string-length($role) = 0 and string-length($type) = 0))])[1]"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="href.target"> + <xsl:with-param name="object" select="."/> + <xsl:with-param name="context" select="(//index[count(ancestor::node()|$scope) = count(ancestor::node()) and ($role = @role or $type = @type or (string-length($role) = 0 and string-length($type) = 0))] | //setindex[count(ancestor::node()|$scope) = count(ancestor::node()) and ($role = @role or $type = @type or (string-length($role) = 0 and string-length($type) = 0))])[1]"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + + </xsl:attribute> + + <xsl:value-of select="$title"/> <!-- text only --> + </a> + + <xsl:variable name="id" select="(@id|@xml:id)[1]"/> + <xsl:if test="key('endofrange', $id)[count(ancestor::node()|$scope) = count(ancestor::node()) and ($role = @role or $type = @type or (string-length($role) = 0 and string-length($type) = 0))]"> + <xsl:apply-templates select="key('endofrange', $id)[count(ancestor::node()|$scope) = count(ancestor::node()) and ($role = @role or $type = @type or (string-length($role) = 0 and string-length($type) = 0))][last()]" mode="reference"> + <xsl:with-param name="position" select="position()"/> + <xsl:with-param name="scope" select="$scope"/> + <xsl:with-param name="role" select="$role"/> + <xsl:with-param name="type" select="$type"/> + <xsl:with-param name="separator" select="$range.separator"/> + </xsl:apply-templates> + </xsl:if> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +<xsl:template name="reference"> + <xsl:param name="scope" select="."/> + <xsl:param name="role" select="''"/> + <xsl:param name="type" select="''"/> + <xsl:param name="zones"/> + + <xsl:choose> + <xsl:when test="contains($zones, ' ')"> + <xsl:variable name="zone" select="substring-before($zones, ' ')"/> + <xsl:variable name="target" select="key('sections', $zone)"/> + + <a> + <xsl:apply-templates select="." mode="class.attribute"/> +<!-- Optimization for pgsql-docs: this call adds nothing but fails with docbook-xsl 1.76 --> +<!-- <xsl:call-template name="id.attribute"/> --> + <xsl:attribute name="href"> + <xsl:call-template name="href.target"> + <xsl:with-param name="object" select="$target[1]"/> + <xsl:with-param name="context" select="//index[count(ancestor::node()|$scope) = count(ancestor::node()) and ($role = @role or $type = @type or (string-length($role) = 0 and string-length($type) = 0))][1]"/> + </xsl:call-template> + </xsl:attribute> + <xsl:apply-templates select="$target[1]" mode="index-title-content"/> + </a> + <xsl:text>, </xsl:text> + <xsl:call-template name="reference"> + <xsl:with-param name="zones" select="substring-after($zones, ' ')"/> + <xsl:with-param name="position" select="position()"/> + <xsl:with-param name="scope" select="$scope"/> + <xsl:with-param name="role" select="$role"/> + <xsl:with-param name="type" select="$type"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:variable name="zone" select="$zones"/> + <xsl:variable name="target" select="key('sections', $zone)"/> + + <a> + <xsl:apply-templates select="." mode="class.attribute"/> +<!-- Optimization for pgsql-docs: this call adds nothing but fails with docbook-xsl 1.76 --> +<!-- <xsl:call-template name="id.attribute"/> --> + <xsl:attribute name="href"> + <xsl:call-template name="href.target"> + <xsl:with-param name="object" select="$target[1]"/> + <!-- Optimization for pgsql-docs: Only look for index under book + instead of searching the whole node tree. --> + <!-- <xsl:with-param name="context" select="//index[count(ancestor::node()|$scope) = count(ancestor::node()) and ($role = @role or $type = @type or (string-length($role) = 0 and string-length($type) = 0))][1]"/> --> + <xsl:with-param name="context" select="/book/index[count(ancestor::node()|$scope) = count(ancestor::node()) and ($role = @role or $type = @type or (string-length($role) = 0 and string-length($type) = 0))][1]"/> + </xsl:call-template> + </xsl:attribute> + <xsl:apply-templates select="$target[1]" mode="index-title-content"/> + </a> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + + +<!-- from xhtml/chunk-common.xsl --> + +<xsl:template name="chunk-all-sections"> + <xsl:param name="content"> + <xsl:apply-imports/> + </xsl:param> + + <!-- Optimization for pgsql-docs: Since we set a fixed $chunk.section.depth, + we can do away with a bunch of complicated XPath searches for the + previous and next sections at various levels. --> + + <xsl:if test="$chunk.section.depth != 1"> + <xsl:message terminate="yes"> + <xsl:text>Error: If you change $chunk.section.depth, then you must update the performance-optimized chunk-all-sections-template.</xsl:text> + </xsl:message> + </xsl:if> + + <xsl:variable name="prev" + select="(preceding::book[1] + |preceding::preface[1] + |preceding::chapter[1] + |preceding::appendix[1] + |preceding::part[1] + |preceding::reference[1] + |preceding::refentry[1] + |preceding::colophon[1] + |preceding::article[1] + |preceding::topic[1] + |preceding::bibliography[parent::article or parent::book or parent::part][1] + |preceding::glossary[parent::article or parent::book or parent::part][1] + |preceding::index[$generate.index != 0] + [parent::article or parent::book or parent::part][1] + |preceding::setindex[$generate.index != 0][1] + |ancestor::set + |ancestor::book[1] + |ancestor::preface[1] + |ancestor::chapter[1] + |ancestor::appendix[1] + |ancestor::part[1] + |ancestor::reference[1] + |ancestor::article[1] + |ancestor::topic[1] + |preceding::sect1[1] + |ancestor::sect1[1])[last()]"/> + + <xsl:variable name="next" + select="(following::book[1] + |following::preface[1] + |following::chapter[1] + |following::appendix[1] + |following::part[1] + |following::reference[1] + |following::refentry[1] + |following::colophon[1] + |following::bibliography[parent::article or parent::book or parent::part][1] + |following::glossary[parent::article or parent::book or parent::part][1] + |following::index[$generate.index != 0] + [parent::article or parent::book][1] + |following::article[1] + |following::topic[1] + |following::setindex[$generate.index != 0][1] + |descendant::book[1] + |descendant::preface[1] + |descendant::chapter[1] + |descendant::appendix[1] + |descendant::article[1] + |descendant::topic[1] + |descendant::bibliography[parent::article or parent::book][1] + |descendant::glossary[parent::article or parent::book or parent::part][1] + |descendant::index[$generate.index != 0] + [parent::article or parent::book][1] + |descendant::colophon[1] + |descendant::setindex[$generate.index != 0][1] + |descendant::part[1] + |descendant::reference[1] + |descendant::refentry[1] + |following::sect1[1] + |descendant::sect1[1])[1]"/> + + <xsl:call-template name="process-chunk"> + <xsl:with-param name="prev" select="$prev"/> + <xsl:with-param name="next" select="$next"/> + <xsl:with-param name="content" select="$content"/> + </xsl:call-template> +</xsl:template> + +<xsl:template name="href.target"> + <xsl:param name="context" select="."/> + <xsl:param name="object" select="."/> + <xsl:param name="toc-context" select="."/> + <!-- Optimization for pgsql-docs: Remove support for dbhtml processing + instruction here --> + <xsl:variable name="href.to.uri"> + <xsl:call-template name="href.target.uri"> + <xsl:with-param name="object" select="$object"/> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="href.from.uri"> + <xsl:choose> + <xsl:when test="not($toc-context = .)"> + <xsl:call-template name="href.target.uri"> + <xsl:with-param name="object" select="$toc-context"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="href.target.uri"> + <xsl:with-param name="object" select="$context"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:variable name="href.to"> + <xsl:value-of select="$href.to.uri"/> + </xsl:variable> + <xsl:variable name="href.from"> + <xsl:call-template name="trim.common.uri.paths"> + <xsl:with-param name="uriA" select="$href.to.uri"/> + <xsl:with-param name="uriB" select="$href.from.uri"/> + <xsl:with-param name="return" select="'B'"/> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="depth"> + <xsl:call-template name="count.uri.path.depth"> + <xsl:with-param name="filename" select="$href.from"/> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="href"> + <xsl:call-template name="copy-string"> + <xsl:with-param name="string" select="'../'"/> + <xsl:with-param name="count" select="$depth"/> + </xsl:call-template> + <xsl:value-of select="$href.to"/> + </xsl:variable> + <xsl:value-of select="$href"/> +</xsl:template> + +<xsl:template name="html.head"> + <xsl:param name="prev" select="/foo"/> + <xsl:param name="next" select="/foo"/> + + <!-- Optimization for pgsql-docs: Cut out a bunch of things we don't need + here, including an expensive //legalnotice search. --> + + <head> + <xsl:call-template name="system.head.content"/> + <xsl:call-template name="head.content"/> + + <xsl:if test="$prev"> + <link rel="prev"> + <xsl:attribute name="href"> + <xsl:call-template name="href.target"> + <xsl:with-param name="object" select="$prev"/> + </xsl:call-template> + </xsl:attribute> + <xsl:attribute name="title"> + <xsl:apply-templates select="$prev" mode="object.title.markup.textonly"/> + </xsl:attribute> + </link> + </xsl:if> + + <xsl:if test="$next"> + <link rel="next"> + <xsl:attribute name="href"> + <xsl:call-template name="href.target"> + <xsl:with-param name="object" select="$next"/> + </xsl:call-template> + </xsl:attribute> + <xsl:attribute name="title"> + <xsl:apply-templates select="$next" mode="object.title.markup.textonly"/> + </xsl:attribute> + </link> + </xsl:if> + + <xsl:call-template name="user.head.content"/> + </head> +</xsl:template> + +</xsl:stylesheet> diff --git a/doc/src/sgml/stylesheet-text.xsl b/doc/src/sgml/stylesheet-text.xsl new file mode 100644 index 0000000000..476b871870 --- /dev/null +++ b/doc/src/sgml/stylesheet-text.xsl @@ -0,0 +1,98 @@ +<?xml version='1.0'?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version='1.0' + xmlns="http://www.w3.org/TR/xhtml1/transitional" + exclude-result-prefixes="#default"> + +<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"/> +<xsl:import href="stylesheet-common.xsl" /> + +<!-- The customizations here are somewhat random in order to make the text + output look good. --> + +<!-- no section numbers or ToC --> +<xsl:param name="chapter.autolabel" select="0"/> +<xsl:param name="section.autolabel" select="0"/> +<xsl:param name="generate.toc"></xsl:param> + +<!-- don't need them, and they mess up formatting --> +<xsl:template match="indexterm"> +</xsl:template> + +<xsl:template match="step"> + <li> + <xsl:call-template name="common.html.attributes"/> + <xsl:call-template name="id.attribute"/> +<!-- messes up formatting + <xsl:call-template name="anchor"/> +--> + <xsl:apply-templates/> + </li> +</xsl:template> + +<!-- produce "ASCII markup" for emphasis and such --> + +<xsl:template match="emphasis"> + <xsl:text>*</xsl:text> + <xsl:apply-templates/> + <xsl:text>*</xsl:text> +</xsl:template> + +<xsl:template match="para/command|para/filename|para/option|para/replaceable"> + <xsl:call-template name="gentext.startquote"/> + <xsl:apply-templates/> + <xsl:call-template name="gentext.endquote"/> +</xsl:template> + +<xsl:template match="filename/replaceable|firstterm"> + <xsl:apply-templates/> +</xsl:template> + +<!-- tweak formatting for note, warning, etc. --> +<xsl:template name="nongraphical.admonition"> + <div> + <xsl:call-template name="common.html.attributes"> + <xsl:with-param name="inherit" select="1"/> + </xsl:call-template> + <xsl:call-template name="id.attribute"/> + + <xsl:if test="$admon.textlabel != 0 or title or info/title"> + <p> + <b> + <xsl:call-template name="anchor"/> + <xsl:apply-templates select="." mode="object.title.markup"/>: + </b> + </p> + </xsl:if> + + <xsl:apply-templates/> + </div> +</xsl:template> + +<!-- horizontal rules before titles (matches old DSSSL style) --> + +<xsl:template match="sect1/title + |sect1/info/title + |sect1info/title" + mode="titlepage.mode" priority="2"> + <hr/> + <xsl:call-template name="section.title"/> +</xsl:template> + +<xsl:template match="sect2/title + |sect2/info/title + |sect2info/title" + mode="titlepage.mode" priority="2"> + <hr/> + <xsl:call-template name="section.title"/> +</xsl:template> + +<xsl:template match="sect3/title + |sect3/info/title + |sect3info/title" + mode="titlepage.mode" priority="2"> + <hr/> + <xsl:call-template name="section.title"/> +</xsl:template> + +</xsl:stylesheet> diff --git a/doc/src/sgml/stylesheet.css b/doc/src/sgml/stylesheet.css index 60dcc76209..c355fbecac 100644 --- a/doc/src/sgml/stylesheet.css +++ b/doc/src/sgml/stylesheet.css @@ -2,18 +2,18 @@ /* color scheme similar to www.postgresql.org */ -BODY { +body { color: #000000; background: #FFFFFF; font-family: verdana, sans-serif; } -A:link { color:#0066A2; } -A:visited { color:#004E66; } -A:active { color:#0066A2; } -A:hover { color:#000000; } +a:link { color:#0066A2; } +a:visited { color:#004E66; } +a:active { color:#0066A2; } +a:hover { color:#000000; } -H1 { +h1 { font-size: 1.4em; font-weight: bold; margin-top: 0em; @@ -21,34 +21,39 @@ H1 { color: #EC5800; } -H2 { +h2 { font-size: 1.2em; margin: 1.2em 0em 1.2em 0em; font-weight: bold; color: #666; } -H3 { +.titlepage h2.title, +.refnamediv h2 { + color: #EC5800; +} + +h3 { font-size: 1.1em; margin: 1.2em 0em 1.2em 0em; font-weight: bold; color: #666; } -H4 { +h4 { font-size: 0.95em; margin: 1.2em 0em 1.2em 0em; font-weight: normal; color: #666; } -H5 { +h5 { font-size: 0.9em; margin: 1.2em 0em 1.2em 0em; font-weight: normal; } -H6 { +h6 { font-size: 0.85em; margin: 1.2em 0em 1.2em 0em; font-weight: normal; @@ -56,13 +61,13 @@ H6 { /* center some titles */ -.BOOK .TITLE, .BOOK .CORPAUTHOR, .BOOK .COPYRIGHT { +.book .title, .book .corpauthor, .book .copyright { text-align: center; } /* decoration for formal examples */ -DIV.EXAMPLE { +div.example { padding-left: 15px; border-style: solid; border-width: 0px; @@ -71,28 +76,29 @@ DIV.EXAMPLE { margin: 0.5ex; } -/* less dense spacing of TOC */ - -.BOOK .TOC DL DT { - padding-top: 1.5ex; - padding-bottom: 1.5ex; -} - -.BOOK .TOC DL DL DT { - padding-top: 0ex; - padding-bottom: 0ex; +/* Put these here instead of inside the HTML (see unsetting of + admon.style in XSL) so that the web site stylesheet can set its own + style. */ + +.tip, +.note, +.important, +.caution, +.warning { + margin-left: 0.5in; + margin-right: 0.5in; } /* miscellaneous */ -PRE.LITERALLAYOUT, .SCREEN, .SYNOPSIS, .PROGRAMLISTING { +pre.literallayout, .screen, .synopsis, .programlisting { margin-left: 4ex; } -.COMMENT { color: red; } +.comment { color: red; } -VAR { font-family: monospace; font-style: italic; } +var { font-family: monospace; font-style: italic; } /* Konqueror's standard style for ACRONYM is italic. */ -ACRONYM { font-style: inherit; } +acronym { font-style: inherit; } -.OPTION { white-space: nowrap; } +.option { white-space: nowrap; } diff --git a/doc/src/sgml/stylesheet.dsl b/doc/src/sgml/stylesheet.dsl deleted file mode 100644 index 61d2963b17..0000000000 --- a/doc/src/sgml/stylesheet.dsl +++ /dev/null @@ -1,841 +0,0 @@ -<!-- doc/src/sgml/stylesheet.dsl --> -<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ - -<!-- must turn on one of these with -i on the jade command line --> -<!ENTITY % output-html "IGNORE"> -<!ENTITY % output-print "IGNORE"> -<!ENTITY % output-text "IGNORE"> - -<![ %output-html; [ -<!ENTITY dbstyle PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL> -]]> - -<![ %output-print; [ -<!ENTITY dbstyle PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA DSSSL> -]]> - -<![ %output-text; [ -<!ENTITY dbstyle PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL> -]]> - -]> - -<style-sheet> - <style-specification use="docbook"> - <style-specification-body> - -<!-- general customization ......................................... --> - -<!-- (applicable to all output formats) --> - -(define draft-mode #f) - -(define pgsql-docs-list "[email protected]") - -;; Don't show manpage volume numbers -(define %refentry-xref-manvolnum% #f) - -;; Don't use graphics for callouts. (We could probably do that, but -;; it needs extra work.) -(define %callout-graphics% #f) - -;; Show comments during the development stage. -(define %show-comments% draft-mode) - -;; Don't append period if run-in title ends with any of these -;; characters. We had to add the colon here. This is fixed in -;; stylesheets version 1.71, so it can be removed sometime. -(define %content-title-end-punct% - '(#\. #\! #\? #\:)) - -;; No automatic punctuation after honorific name parts -(define %honorific-punctuation% "") - -;; Change display of some elements -(element command ($mono-seq$)) -(element envar ($mono-seq$)) -(element lineannotation ($italic-seq$)) -(element literal ($mono-seq$)) -(element option ($mono-seq$)) -(element parameter ($mono-seq$)) -(element structfield ($mono-seq$)) -(element structname ($mono-seq$)) -(element symbol ($mono-seq$)) -(element token ($mono-seq$)) -(element type ($mono-seq$)) -(element varname ($mono-seq$)) -(element (programlisting emphasis) ($bold-seq$)) ;; to highlight sections of code - -;; Special support for Tcl synopses -(element optional - (if (equal? (attribute-string (normalize "role")) "tcl") - (make sequence - (literal "?") - ($charseq$) - (literal "?")) - (make sequence - (literal %arg-choice-opt-open-str%) - ($charseq$) - (literal %arg-choice-opt-close-str%)))) - -;; Avoid excessive cross-reference labels -(define (auto-xref-indirect? target ancestor) - (cond -; ;; Always add indirect references to another book -; ((member (gi ancestor) (book-element-list)) -; #t) - ;; Add indirect references to the section or component a block - ;; is in iff chapters aren't autolabelled. (Otherwise "Figure 1-3" - ;; is sufficient) - ((and (member (gi target) (block-element-list)) - (not %chapter-autolabel%)) - #t) - ;; Add indirect references to the component a section is in if - ;; the sections are not autolabelled - ((and (member (gi target) (section-element-list)) - (member (gi ancestor) (component-element-list)) - (not %section-autolabel%)) - #t) - (else #f))) - - -;; Bibliography things - -;; Use the titles of bibliography entries in cross-references -(define biblio-xref-title #t) - -;; Process bibliography entry components in the order shown below, not -;; in the order they appear in the document. (I suppose this should -;; be made to fit some publishing standard.) -(define %biblioentry-in-entry-order% #f) - -(define (biblioentry-inline-elements) - (list - (normalize "author") - (normalize "authorgroup") - (normalize "title") - (normalize "subtitle") - (normalize "volumenum") - (normalize "edition") - (normalize "othercredit") - (normalize "contrib") - (normalize "editor") - (normalize "publishername") - (normalize "confgroup") - (normalize "publisher") - (normalize "isbn") - (normalize "issn") - (normalize "pubsnumber") - (normalize "date") - (normalize "pubdate") - (normalize "pagenums") - (normalize "bibliomisc"))) - -(mode biblioentry-inline-mode - - (element confgroup - (make sequence - (literal "Proc. ") - (next-match))) - - (element isbn - (make sequence - (literal "ISBN ") - (process-children))) - - (element issn - (make sequence - (literal "ISSN ") - (process-children)))) - - -;; The rules in the default stylesheet for productname format it as a -;; paragraph. This may be suitable for productname directly within -;; *info, but it's nonsense when productname is used inline, as we do. -(mode book-titlepage-recto-mode - (element (para productname) ($charseq$))) -(mode book-titlepage-verso-mode - (element (para productname) ($charseq$))) -;; Add more here if needed... - - -;; Replace a sequence of whitespace in a string by a single space -(define (normalize-whitespace str #!optional (whitespace '(#\space #\U-000D))) - (let loop ((characters (string->list str)) - (result '()) - (prev-was-space #f)) - (if (null? characters) - (list->string (reverse result)) - (let ((c (car characters)) - (rest (cdr characters))) - (if (member c whitespace) - (if prev-was-space - (loop rest result #t) - (loop rest (cons #\space result) #t)) - (loop rest (cons c result) #f)))))) - - -<!-- HTML output customization ..................................... --> - -<![ %output-html; [ - -(define %section-autolabel% #t) -(define %label-preface-sections% #f) -(define %generate-legalnotice-link% #t) -(define %html-ext% ".html") -(define %root-filename% "index") -(define %link-mailto-url% (string-append "mailto:" pgsql-docs-list)) -(define %use-id-as-filename% #t) -(define website-stylesheet #f) -(define %stylesheet% (if website-stylesheet "http://www.postgresql.org/media/css/docs.css" "stylesheet.css")) -(define %graphic-default-extension% "gif") -(define %body-attr% '()) -(define ($generate-book-lot-list$) '()) -(define use-output-dir #t) -(define %output-dir% "html") -(define html-index-filename "../HTML.index") - - -;; Only build HTML.index or the actual HTML output, not both. Saves a -;; *lot* of time. (overrides docbook.dsl) -(root - (if (not html-index) - (make sequence - (process-children) - (with-mode manifest - (process-children))) - (with-mode htmlindex - (process-children)))) - - -;; Do not combine first section into chapter chunk. -(define (chunk-skip-first-element-list) '()) - -;; Returns the depth of auto TOC that should be made at the nd-level -(define (toc-depth nd) - (cond ((string=? (gi nd) (normalize "book")) 2) - ((string=? (gi nd) (normalize "part")) 2) - ((string=? (gi nd) (normalize "chapter")) 2) - (else 1))) - -;; Add character encoding and time of creation into HTML header -(define %html-header-tags% - (list (list "META" '("HTTP-EQUIV" "Content-Type") '("CONTENT" "text/html; charset=ISO-8859-1")) - (list "META" '("NAME" "creation") (list "CONTENT" (time->string (time) #t))))) - - -;; Block elements are allowed in PARA in DocBook, but not in P in -;; HTML. With %fix-para-wrappers% turned on, the stylesheets attempt -;; to avoid putting block elements in HTML P tags by outputting -;; additional end/begin P pairs around them. -(define %fix-para-wrappers% #t) - -;; ...but we need to do some extra work to make the above apply to PRE -;; as well. (mostly pasted from dbverb.dsl) -(define ($verbatim-display$ indent line-numbers?) - (let ((content (make element gi: "PRE" - attributes: (list - (list "CLASS" (gi))) - (if (or indent line-numbers?) - ($verbatim-line-by-line$ indent line-numbers?) - (process-children))))) - (if %shade-verbatim% - (make element gi: "TABLE" - attributes: ($shade-verbatim-attr$) - (make element gi: "TR" - (make element gi: "TD" - content))) - (make sequence - (para-check) - content - (para-check 'restart))))) - -;; ...and for notes. -(element note - (make sequence - (para-check) - ($admonition$) - (para-check 'restart))) - -;;; XXX The above is very ugly. It might be better to run 'tidy' on -;;; the resulting *.html files. - - -;; Format multiple terms in varlistentry vertically, instead -;; of comma-separated. -(element (varlistentry term) - (make sequence - (process-children-trim) - (if (not (last-sibling?)) - (make empty-element gi: "BR") - (empty-sosofo)))) - - -;; Customization of header -;; - make title a link to the home page -;; - add tool tips to Prev/Next links -;; - add Up link -;; (overrides dbnavig.dsl) -(define (default-header-nav-tbl-noff elemnode prev next prevsib nextsib) - (let* ((r1? (nav-banner? elemnode)) - (r1-sosofo (make element gi: "TR" - (make element gi: "TH" - attributes: (list - (list "COLSPAN" "4") - (list "ALIGN" "center") - (list "VALIGN" "bottom")) - (make element gi: "A" - attributes: (list - (list "HREF" (href-to (nav-home elemnode)))) - (nav-banner elemnode))))) - (r2? (or (not (node-list-empty? prev)) - (not (node-list-empty? next)) - (nav-context? elemnode))) - (r2-sosofo (make element gi: "TR" - (make element gi: "TD" - attributes: (list - (list "WIDTH" "10%") - (list "ALIGN" "left") - (list "VALIGN" "top")) - (if (node-list-empty? prev) - (make entity-ref name: "nbsp") - (make element gi: "A" - attributes: (list - (list "TITLE" (element-title-string prev)) - (list "HREF" - (href-to - prev)) - (list "ACCESSKEY" - "P")) - (gentext-nav-prev prev)))) - (make element gi: "TD" - attributes: (list - (list "WIDTH" "10%") - (list "ALIGN" "left") - (list "VALIGN" "top")) - (if (nav-up? elemnode) - (nav-up elemnode) - (nav-home-link elemnode))) - (make element gi: "TD" - attributes: (list - (list "WIDTH" "60%") - (list "ALIGN" "center") - (list "VALIGN" "bottom")) - (nav-context elemnode)) - (make element gi: "TD" - attributes: (list - (list "WIDTH" "20%") - (list "ALIGN" "right") - (list "VALIGN" "top")) - (if (node-list-empty? next) - (make entity-ref name: "nbsp") - (make element gi: "A" - attributes: (list - (list "TITLE" (element-title-string next)) - (list "HREF" - (href-to - next)) - (list "ACCESSKEY" - "N")) - (gentext-nav-next next))))))) - (if (or r1? r2?) - (make element gi: "DIV" - attributes: '(("CLASS" "NAVHEADER")) - (make element gi: "TABLE" - attributes: (list - (list "SUMMARY" "Header navigation table") - (list "WIDTH" %gentext-nav-tblwidth%) - (list "BORDER" "0") - (list "CELLPADDING" "0") - (list "CELLSPACING" "0")) - (if r1? r1-sosofo (empty-sosofo)) - (if r2? r2-sosofo (empty-sosofo))) - (make empty-element gi: "HR" - attributes: (list - (list "ALIGN" "LEFT") - (list "WIDTH" %gentext-nav-tblwidth%)))) - (empty-sosofo)))) - - -;; Put index "quicklinks" (A | B | C | ...) at the top of the bookindex page. - -(element index - (let ((preamble (node-list-filter-by-not-gi - (children (current-node)) - (list (normalize "indexentry")))) - (indexdivs (node-list-filter-by-gi - (children (current-node)) - (list (normalize "indexdiv")))) - (entries (node-list-filter-by-gi - (children (current-node)) - (list (normalize "indexentry"))))) - (html-document - (with-mode head-title-mode - (literal (element-title-string (current-node)))) - (make element gi: "DIV" - attributes: (list (list "CLASS" (gi))) - ($component-separator$) - ($component-title$) - (if (node-list-empty? indexdivs) - (empty-sosofo) - (make element gi: "P" - attributes: (list (list "CLASS" "INDEXDIV-QUICKLINKS")) - (with-mode indexdiv-quicklinks-mode - (process-node-list indexdivs)))) - (process-node-list preamble) - (if (node-list-empty? entries) - (empty-sosofo) - (make element gi: "DL" - (process-node-list entries))))))) - - -(mode indexdiv-quicklinks-mode - (element indexdiv - (make sequence - (make element gi: "A" - attributes: (list (list "HREF" (href-to (current-node)))) - (element-title-sosofo)) - (if (not (last-sibling?)) - (literal " | ") - (literal ""))))) - - -;; Changed to strip and normalize index term content (overrides -;; dbindex.dsl) -(define (htmlindexterm) - (let* ((attr (gi (current-node))) - (content (data (current-node))) - (string (strip (normalize-whitespace content))) ;; changed - (sortas (attribute-string (normalize "sortas")))) - (make sequence - (make formatting-instruction data: attr) - (if sortas - (make sequence - (make formatting-instruction data: "[") - (make formatting-instruction data: sortas) - (make formatting-instruction data: "]")) - (empty-sosofo)) - (make formatting-instruction data: " ") - (make formatting-instruction data: string) - (htmlnewline)))) - - -]]> <!-- %output-html --> - - -<!-- Print output customization .................................... --> - -<![ %output-print; [ - -(define %section-autolabel% #t) -(define %default-quadding% 'justify) - -;; Don't know how well hyphenation works with other backends. Might -;; turn this on if desired. -(define %hyphenation% - (if tex-backend #t #f)) - -;; Put footnotes at the bottom of the page (rather than end of -;; section), and put the URLs of links into footnotes. -;; -;; bop-footnotes only works with TeX, otherwise it's ignored. But -;; when both of these are #t and TeX is used, you need at least -;; stylesheets 1.73 because otherwise you don't get any footnotes at -;; all for the links. -(define bop-footnotes #t) -(define %footnote-ulinks% #t) - -(define %refentry-new-page% #t) -(define %refentry-keep% #f) - -;; Disabled because of TeX problems -;; (http://archives.postgresql.org/pgsql-docs/2007-12/msg00056.php) -(define ($generate-book-lot-list$) '()) - -;; Indentation of verbatim environments. (This should really be done -;; with start-indent in DSSSL.) -;; Use of indentation in this area exposes a bug in openjade, -;; http://archives.postgresql.org/pgsql-docs/2006-12/msg00064.php -;; (define %indent-programlisting-lines% " ") -;; (define %indent-screen-lines% " ") -;; (define %indent-synopsis-lines% " ") - - -;; Default graphic format: Jadetex wants eps, pdfjadetex wants pdf. -;; (Note that pdfjadetex will not accept eps, that's why we need to -;; create a different .tex file for each.) What works with RTF? - -(define texpdf-output #f) ;; override from command line - -(define %graphic-default-extension% - (cond (tex-backend (if texpdf-output "pdf" "eps")) - (rtf-backend "gif") - (else "XXX"))) - -;; Need to add pdf here so that the above works. Default setup -;; doesn't know about PDF. -(define preferred-mediaobject-extensions - (list "eps" "ps" "jpg" "jpeg" "pdf" "png")) - - -;; Don't show links when citing a bibliography entry. This fouls up -;; the footnumber counting. To get the link, one can still look into -;; the bibliography itself. -(mode xref-title-mode - (element ulink - (process-children))) - - -;; Format legalnotice justified and with space between paragraphs. -(mode book-titlepage-verso-mode - (element (legalnotice para) - (make paragraph - use: book-titlepage-verso-style ;; alter this if ever it needs to appear elsewhere - quadding: %default-quadding% - line-spacing: (* 0.8 (inherited-line-spacing)) - font-size: (* 0.8 (inherited-font-size)) - space-before: (* 0.8 %para-sep%) - space-after: (* 0.8 %para-sep%) - first-line-start-indent: (if (is-first-para) - (* 0.8 %para-indent-firstpara%) - (* 0.8 %para-indent%)) - (process-children)))) - - -;; Fix spacing problems in variablelists - -(element (varlistentry term) - (make paragraph - space-before: (if (first-sibling?) - %para-sep% - 0pt) - keep-with-next?: #t - (process-children))) - -(define %varlistentry-indent% 2em) - -(element (varlistentry listitem) - (make sequence - start-indent: (+ (inherited-start-indent) %varlistentry-indent%) - (process-children))) - - -;; Whitespace fixes for itemizedlists and orderedlists - -(define (process-listitem-content) - (if (absolute-first-sibling?) - (make sequence - (process-children-trim)) - (next-match))) - - -;; Default stylesheets format simplelists as tables. This spells -;; trouble for Jade. So we just format them as plain lines. - -(define %simplelist-indent% 1em) - -(define (my-simplelist-vert members) - (make display-group - space-before: %para-sep% - space-after: %para-sep% - start-indent: (+ %simplelist-indent% (inherited-start-indent)) - (process-children))) - -(element simplelist - (let ((type (attribute-string (normalize "type"))) - (cols (if (attribute-string (normalize "columns")) - (if (> (string->number (attribute-string (normalize "columns"))) 0) - (string->number (attribute-string (normalize "columns"))) - 1) - 1)) - (members (select-elements (children (current-node)) (normalize "member")))) - (cond - ((equal? type (normalize "inline")) - (if (equal? (gi (parent (current-node))) - (normalize "para")) - (process-children) - (make paragraph - space-before: %para-sep% - space-after: %para-sep% - start-indent: (inherited-start-indent)))) - ((equal? type (normalize "vert")) - (my-simplelist-vert members)) - ((equal? type (normalize "horiz")) - (simplelist-table 'row cols members))))) - -(element member - (let ((type (inherited-attribute-string (normalize "type")))) - (cond - ((equal? type (normalize "inline")) - (make sequence - (process-children) - (if (not (last-sibling?)) - (literal ", ") - (literal "")))) - ((equal? type (normalize "vert")) - (make paragraph - space-before: 0pt - space-after: 0pt)) - ((equal? type (normalize "horiz")) - (make paragraph - quadding: 'start - (process-children)))))) - - -;; Jadetex doesn't handle links to the content of tables, so -;; indexterms that point to table entries will go nowhere. We fix -;; this by pointing the index entry to the table itself instead, which -;; should be equally useful in practice. - -(define (find-parent-table nd) - (let ((table (ancestor-member nd ($table-element-list$)))) - (if (node-list-empty? table) - nd - table))) - -;; (The function below overrides the one in print/dbindex.dsl.) - -(define (indexentry-link nd) - (let* ((id (attribute-string (normalize "role") nd)) - (prelim-target (find-indexterm id)) - (target (find-parent-table prelim-target)) - (preferred (not (node-list-empty? - (select-elements (children (current-node)) - (normalize "emphasis"))))) - (sosofo (if (node-list-empty? target) - (literal "?") - (make link - destination: (node-list-address target) - (with-mode toc-page-number-mode - (process-node-list target)))))) - (if preferred - (make sequence - font-weight: 'bold - sosofo) - sosofo))) - - -;; By default, the part and reference title pages get wrong page -;; numbers: The first title page gets roman numerals carried over from -;; preface/toc -- we want Arabic numerals. We also need to make sure -;; that page-number-restart is set of #f explicitly, because otherwise -;; it will carry over from the previous component, which is not good. -;; -;; (This looks worse than it is. It's copied from print/dbttlpg.dsl -;; and common/dbcommon.dsl and modified in minor detail.) - -(define (first-part?) - (let* ((book (ancestor (normalize "book"))) - (nd (ancestor-member (current-node) - (append - (component-element-list) - (division-element-list)))) - (bookch (children book))) - (let loop ((nl bookch)) - (if (node-list-empty? nl) - #f - (if (equal? (gi (node-list-first nl)) (normalize "part")) - (if (node-list=? (node-list-first nl) nd) - #t - #f) - (loop (node-list-rest nl))))))) - -(define (first-reference?) - (let* ((book (ancestor (normalize "book"))) - (nd (ancestor-member (current-node) - (append - (component-element-list) - (division-element-list)))) - (bookch (children book))) - (let loop ((nl bookch)) - (if (node-list-empty? nl) - #f - (if (equal? (gi (node-list-first nl)) (normalize "reference")) - (if (node-list=? (node-list-first nl) nd) - #t - #f) - (loop (node-list-rest nl))))))) - - -(define (part-titlepage elements #!optional (side 'recto)) - (let ((nodelist (titlepage-nodelist - (if (equal? side 'recto) - (reference-titlepage-recto-elements) - (reference-titlepage-verso-elements)) - elements)) - ;; partintro is a special case... - (partintro (node-list-first - (node-list-filter-by-gi elements (list (normalize "partintro")))))) - (if (part-titlepage-content? elements side) - (make simple-page-sequence - page-n-columns: %titlepage-n-columns% - ;; Make sure that page number format is correct. - page-number-format: ($page-number-format$) - ;; Make sure that the page number is set to 1 if this is the - ;; first part in the book - page-number-restart?: (first-part?) - input-whitespace-treatment: 'collapse - use: default-text-style - - ;; This hack is required for the RTF backend. If an external-graphic - ;; is the first thing on the page, RTF doesn't seem to do the right - ;; thing (the graphic winds up on the baseline of the first line - ;; of the page, left justified). This "one point rule" fixes - ;; that problem. - (make paragraph - line-spacing: 1pt - (literal "")) - - (let loop ((nl nodelist) (lastnode (empty-node-list))) - (if (node-list-empty? nl) - (empty-sosofo) - (make sequence - (if (or (node-list-empty? lastnode) - (not (equal? (gi (node-list-first nl)) - (gi lastnode)))) - (part-titlepage-before (node-list-first nl) side) - (empty-sosofo)) - (cond - ((equal? (gi (node-list-first nl)) (normalize "subtitle")) - (part-titlepage-subtitle (node-list-first nl) side)) - ((equal? (gi (node-list-first nl)) (normalize "title")) - (part-titlepage-title (node-list-first nl) side)) - (else - (part-titlepage-default (node-list-first nl) side))) - (loop (node-list-rest nl) (node-list-first nl))))) - - (if (and %generate-part-toc% - %generate-part-toc-on-titlepage% - (equal? side 'recto)) - (make display-group - (build-toc (current-node) - (toc-depth (current-node)))) - (empty-sosofo)) - - ;; PartIntro is a special case - (if (and (equal? side 'recto) - (not (node-list-empty? partintro)) - %generate-partintro-on-titlepage%) - ($process-partintro$ partintro #f) - (empty-sosofo))) - - (empty-sosofo)))) - - -(define (reference-titlepage elements #!optional (side 'recto)) - (let ((nodelist (titlepage-nodelist - (if (equal? side 'recto) - (reference-titlepage-recto-elements) - (reference-titlepage-verso-elements)) - elements)) - ;; partintro is a special case... - (partintro (node-list-first - (node-list-filter-by-gi elements (list (normalize "partintro")))))) - (if (reference-titlepage-content? elements side) - (make simple-page-sequence - page-n-columns: %titlepage-n-columns% - ;; Make sure that page number format is correct. - page-number-format: ($page-number-format$) - ;; Make sure that the page number is set to 1 if this is the - ;; first part in the book - page-number-restart?: (first-reference?) - input-whitespace-treatment: 'collapse - use: default-text-style - - ;; This hack is required for the RTF backend. If an external-graphic - ;; is the first thing on the page, RTF doesn't seem to do the right - ;; thing (the graphic winds up on the baseline of the first line - ;; of the page, left justified). This "one point rule" fixes - ;; that problem. - (make paragraph - line-spacing: 1pt - (literal "")) - - (let loop ((nl nodelist) (lastnode (empty-node-list))) - (if (node-list-empty? nl) - (empty-sosofo) - (make sequence - (if (or (node-list-empty? lastnode) - (not (equal? (gi (node-list-first nl)) - (gi lastnode)))) - (reference-titlepage-before (node-list-first nl) side) - (empty-sosofo)) - (cond - ((equal? (gi (node-list-first nl)) (normalize "author")) - (reference-titlepage-author (node-list-first nl) side)) - ((equal? (gi (node-list-first nl)) (normalize "authorgroup")) - (reference-titlepage-authorgroup (node-list-first nl) side)) - ((equal? (gi (node-list-first nl)) (normalize "corpauthor")) - (reference-titlepage-corpauthor (node-list-first nl) side)) - ((equal? (gi (node-list-first nl)) (normalize "editor")) - (reference-titlepage-editor (node-list-first nl) side)) - ((equal? (gi (node-list-first nl)) (normalize "subtitle")) - (reference-titlepage-subtitle (node-list-first nl) side)) - ((equal? (gi (node-list-first nl)) (normalize "title")) - (reference-titlepage-title (node-list-first nl) side)) - (else - (reference-titlepage-default (node-list-first nl) side))) - (loop (node-list-rest nl) (node-list-first nl))))) - - (if (and %generate-reference-toc% - %generate-reference-toc-on-titlepage% - (equal? side 'recto)) - (make display-group - (build-toc (current-node) - (toc-depth (current-node)))) - (empty-sosofo)) - - ;; PartIntro is a special case - (if (and (equal? side 'recto) - (not (node-list-empty? partintro)) - %generate-partintro-on-titlepage%) - ($process-partintro$ partintro #f) - (empty-sosofo))) - - (empty-sosofo)))) - -]]> <!-- %output-print --> - - -<!-- Plain text output customization ............................... --> - -<!-- -This is used for making the INSTALL file and others. We customize the -HTML stylesheets to be suitable for dumping plain text (via Netscape, -Lynx, or similar). ---> - -<![ %output-text; [ - -(define %section-autolabel% #f) -(define %chapter-autolabel% #f) -(define $generate-chapter-toc$ (lambda () #f)) - -;; For text output, produce "ASCII markup" for emphasis and such. - -(define ($asterix-seq$ #!optional (sosofo (process-children))) - (make sequence - (literal "*") - sosofo - (literal "*"))) - -(define ($dquote-seq$ #!optional (sosofo (process-children))) - (make sequence - (literal (gentext-start-quote)) - sosofo - (literal (gentext-end-quote)))) - -(element (para command) ($dquote-seq$)) -(element (para emphasis) ($asterix-seq$)) -(element (para filename) ($dquote-seq$)) -(element (para option) ($dquote-seq$)) -(element (para replaceable) ($dquote-seq$)) -(element (para userinput) ($dquote-seq$)) - -]]> <!-- %output-text --> - - </style-specification-body> - </style-specification> - - <external-specification id="docbook" document="dbstyle"> -</style-sheet> diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl index 7967b361dd..22dd3b93c6 100644 --- a/doc/src/sgml/stylesheet.xsl +++ b/doc/src/sgml/stylesheet.xsl @@ -6,56 +6,163 @@ <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/> <xsl:include href="stylesheet-common.xsl" /> +<xsl:include href="stylesheet-html-common.xsl" /> +<xsl:include href="stylesheet-speedup-xhtml.xsl" /> <!-- Parameters --> <xsl:param name="base.dir" select="'html/'"></xsl:param> <xsl:param name="use.id.as.filename" select="'1'"></xsl:param> -<xsl:param name="make.valid.html" select="1"></xsl:param> -<xsl:param name="generate.id.attributes" select="1"></xsl:param> <xsl:param name="generate.legalnotice.link" select="1"></xsl:param> -<xsl:param name="link.mailto.url">[email protected]</xsl:param> <xsl:param name="chunk.first.sections" select="1"/> <xsl:param name="chunk.quietly" select="1"></xsl:param> -<xsl:param name="toc.max.depth">2</xsl:param> +<xsl:param name="admon.style"></xsl:param> <!-- handled by CSS stylesheet --> <xsl:param name="website.stylesheet" select="0"/> <xsl:param name="html.stylesheet"> <xsl:choose> <xsl:when test="$website.stylesheet = 0">stylesheet.css</xsl:when> - <xsl:otherwise>http://www.postgresql.org/media/css/docs.css</xsl:otherwise> + <xsl:otherwise>https://www.postgresql.org/media/css/docs.css</xsl:otherwise> </xsl:choose> </xsl:param> -<!-- Change display of some elements --> +<!-- +Customization of header +- add Up and Home links +- add tool tips to links -<xsl:template match="command"> - <xsl:call-template name="inline.monoseq"/> -</xsl:template> +(overrides html/chunk-common.xsl) +--> +<xsl:template name="header.navigation"> + <xsl:param name="prev" select="/foo"/> + <xsl:param name="next" select="/foo"/> + <xsl:param name="nav.context"/> + <xsl:variable name="home" select="/*[1]"/> + <xsl:variable name="up" select="parent::*"/> -<!-- table of contents configuration --> - -<xsl:param name="generate.toc"> -appendix toc,title -article/appendix nop -article toc,title -book toc,title -chapter toc,title -part toc,title -preface toc,title -qandadiv toc -qandaset toc -reference toc,title -sect1 toc -sect2 toc -sect3 toc -sect4 toc -sect5 toc -section toc -set toc,title -</xsl:param> + <xsl:variable name="row1" select="$navig.showtitles != 0"/> + <xsl:variable name="row2" select="count($prev) > 0 + or (count($up) > 0 + and generate-id($up) != generate-id($home) + and $navig.showtitles != 0) + or count($next) > 0"/> + + <xsl:if test="$suppress.navigation = '0' and $suppress.header.navigation = '0'"> + <div class="navheader"> + <xsl:if test="$row1 or $row2"> + <table width="100%" summary="Navigation header"> + <xsl:if test="$row1"> + <tr> + <th colspan="5" align="center"> + <xsl:apply-templates select="." mode="object.title.markup"/> + </th> + </tr> + </xsl:if> + + <xsl:if test="$row2"> + <tr> + <td width="10%" align="{$direction.align.start}"> + <xsl:if test="count($prev)>0"> + <a accesskey="p"> + <xsl:attribute name="href"> + <xsl:call-template name="href.target"> + <xsl:with-param name="object" select="$prev"/> + </xsl:call-template> + </xsl:attribute> + <xsl:attribute name="title"> + <xsl:apply-templates select="$prev" mode="object.title.markup"/> + </xsl:attribute> + <xsl:call-template name="navig.content"> + <xsl:with-param name="direction" select="'prev'"/> + </xsl:call-template> + </a> + </xsl:if> + <xsl:text> </xsl:text> + </td> + <td width="10%" align="{$direction.align.start}"> + <xsl:choose> + <xsl:when test="count($up)>0 + and generate-id($up) != generate-id($home)"> + <a accesskey="u"> + <xsl:attribute name="href"> + <xsl:call-template name="href.target"> + <xsl:with-param name="object" select="$up"/> + </xsl:call-template> + </xsl:attribute> + <xsl:attribute name="title"> + <xsl:apply-templates select="$up" mode="object.title.markup"/> + </xsl:attribute> + <xsl:call-template name="navig.content"> + <xsl:with-param name="direction" select="'up'"/> + </xsl:call-template> + </a> + </xsl:when> + <xsl:otherwise> </xsl:otherwise> + </xsl:choose> + </td> + <th width="60%" align="center"> + <xsl:choose> + <xsl:when test="count($up) > 0 + and generate-id($up) != generate-id($home) + and $navig.showtitles != 0"> + <xsl:apply-templates select="$up" mode="object.title.markup"/> + </xsl:when> + <xsl:otherwise> </xsl:otherwise> + </xsl:choose> + </th> + <td width="10%" align="{$direction.align.end}"> + <xsl:choose> + <xsl:when test="$home != . or $nav.context = 'toc'"> + <a accesskey="h"> + <xsl:attribute name="href"> + <xsl:call-template name="href.target"> + <xsl:with-param name="object" select="$home"/> + </xsl:call-template> + </xsl:attribute> + <xsl:attribute name="title"> + <xsl:apply-templates select="$home" mode="object.title.markup"/> + </xsl:attribute> + <xsl:call-template name="navig.content"> + <xsl:with-param name="direction" select="'home'"/> + </xsl:call-template> + </a> + <xsl:if test="$chunk.tocs.and.lots != 0 and $nav.context != 'toc'"> + <xsl:text> | </xsl:text> + </xsl:if> + </xsl:when> + <xsl:otherwise> </xsl:otherwise> + </xsl:choose> + </td> + <td width="10%" align="{$direction.align.end}"> + <xsl:text> </xsl:text> + <xsl:if test="count($next)>0"> + <a accesskey="n"> + <xsl:attribute name="href"> + <xsl:call-template name="href.target"> + <xsl:with-param name="object" select="$next"/> + </xsl:call-template> + </xsl:attribute> + <xsl:attribute name="title"> + <xsl:apply-templates select="$next" mode="object.title.markup"/> + </xsl:attribute> + <xsl:call-template name="navig.content"> + <xsl:with-param name="direction" select="'next'"/> + </xsl:call-template> + </a> + </xsl:if> + </td> + </tr> + </xsl:if> + </table> + </xsl:if> + <xsl:if test="$header.rule != 0"> + <hr/> + </xsl:if> + </div> + </xsl:if> +</xsl:template> </xsl:stylesheet> diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index 36df6c6b1b..a2d136eaf8 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -1449,12 +1449,13 @@ $1.somecolumn </para> <para> - In a select list (see <xref linkend="queries-select-lists">), you - can ask for all fields of a composite value by + You can ask for all fields of a composite value by writing <literal>.*</literal>: <programlisting> (compositecol).* </programlisting> + This notation behaves differently depending on context; + see <xref linkend="rowtypes-usage"> for details. </para> </sect2> @@ -1531,7 +1532,7 @@ sqrt(2) interchangeable. This behavior is not SQL-standard but is provided in <productname>PostgreSQL</> because it allows use of functions to emulate <quote>computed fields</>. For more information see - <xref linkend="xfunc-sql-composite-functions">. + <xref linkend="rowtypes-usage">. </para> </note> </sect2> @@ -1663,7 +1664,8 @@ SELECT string_agg(a ORDER BY a, ',') FROM table; -- incorrect <para> Placing <literal>ORDER BY</> within the aggregate's regular argument list, as described so far, is used when ordering the input rows for - a <quote>normal</> aggregate for which ordering is optional. There is a + general-purpose and statistical aggregates, for which ordering is + optional. There is a subclass of aggregate functions called <firstterm>ordered-set aggregates</> for which an <replaceable>order_by_clause</replaceable> is <emphasis>required</>, usually because the aggregate's computation is @@ -1674,7 +1676,7 @@ SELECT string_agg(a ORDER BY a, ',') FROM table; -- incorrect inside <literal>WITHIN GROUP (...)</>, as shown in the final syntax alternative above. The expressions in the <replaceable>order_by_clause</replaceable> are evaluated once per - input row just like normal aggregate arguments, sorted as per + input row just like regular aggregate arguments, sorted as per the <replaceable>order_by_clause</replaceable>'s requirements, and fed to the aggregate function as input arguments. (This is unlike the case for a non-<literal>WITHIN GROUP</> <replaceable>order_by_clause</>, @@ -1682,7 +1684,7 @@ SELECT string_agg(a ORDER BY a, ',') FROM table; -- incorrect argument expressions preceding <literal>WITHIN GROUP</>, if any, are called <firstterm>direct arguments</> to distinguish them from the <firstterm>aggregated arguments</> listed in - the <replaceable>order_by_clause</replaceable>. Unlike normal aggregate + the <replaceable>order_by_clause</replaceable>. Unlike regular aggregate arguments, direct arguments are evaluated only once per aggregate call, not once per input row. This means that they can contain variables only if those variables are grouped by <literal>GROUP BY</>; this restriction @@ -1693,11 +1695,18 @@ SELECT string_agg(a ORDER BY a, ',') FROM table; -- incorrect case, write just <literal>()</> not <literal>(*)</>. (<productname>PostgreSQL</> will actually accept either spelling, but only the first way conforms to the SQL standard.) + </para> + + <para> + <indexterm> + <primary>median</primary> + <seealso>percentile</seealso> + </indexterm> An example of an ordered-set aggregate call is: <programlisting> -SELECT percentile_disc(0.5) WITHIN GROUP (ORDER BY income) FROM households; - percentile_disc +SELECT percentile_cont(0.5) WITHIN GROUP (ORDER BY income) FROM households; + percentile_cont ----------------- 50489 </programlisting> @@ -1771,10 +1780,10 @@ FROM generate_series(1,10) AS s(i); <para> A <firstterm>window function call</firstterm> represents the application of an aggregate-like function over some portion of the rows selected - by a query. Unlike regular aggregate function calls, this is not tied + by a query. Unlike non-window aggregate calls, this is not tied to grouping of the selected rows into a single output row — each row remains separate in the query output. However the window function - is able to scan all the rows that would be part of the current row's + has access to all the rows that would be part of the current row's group according to the grouping specification (<literal>PARTITION BY</> list) of the window function call. The syntax of a window function call is one of the following: @@ -1823,20 +1832,20 @@ UNBOUNDED FOLLOWING named window in the <literal>WINDOW</literal> clause; see the <xref linkend="sql-select"> reference page for details. It's worth pointing out that <literal>OVER wname</> is not exactly equivalent to - <literal>OVER (wname)</>; the latter implies copying and modifying the + <literal>OVER (wname ...)</>; the latter implies copying and modifying the window definition, and will be rejected if the referenced window specification includes a frame clause. </para> <para> - The <literal>PARTITION BY</> option groups the rows of the query into + The <literal>PARTITION BY</> clause groups the rows of the query into <firstterm>partitions</>, which are processed separately by the window function. <literal>PARTITION BY</> works similarly to a query-level <literal>GROUP BY</> clause, except that its expressions are always just expressions and cannot be output-column names or numbers. Without <literal>PARTITION BY</>, all rows produced by the query are treated as a single partition. - The <literal>ORDER BY</> option determines the order in which the rows + The <literal>ORDER BY</> clause determines the order in which the rows of a partition are processed by the window function. It works similarly to a query-level <literal>ORDER BY</> clause, but likewise cannot use output-column names or numbers. Without <literal>ORDER BY</>, rows are @@ -1913,17 +1922,17 @@ UNBOUNDED FOLLOWING <para> The built-in window functions are described in <xref linkend="functions-window-table">. Other window functions can be added by - the user. Also, any built-in or user-defined normal aggregate function - can be used as a window function. Ordered-set aggregates presently - cannot be used as window functions, however. + the user. Also, any built-in or user-defined general-purpose or + statistical aggregate can be used as a window function. (Ordered-set + and hypothetical-set aggregates cannot presently be used as window functions.) </para> <para> The syntaxes using <literal>*</> are used for calling parameter-less aggregate functions as window functions, for example <literal>count(*) OVER (PARTITION BY x ORDER BY y)</>. - The asterisk (<literal>*</>) is customarily not used for non-aggregate window functions. - Aggregate window functions, unlike normal aggregate functions, do not + The asterisk (<literal>*</>) is customarily not used for + window-specific functions. Window-specific functions do not allow <literal>DISTINCT</> or <literal>ORDER BY</> to be used within the function argument list. </para> @@ -2291,7 +2300,8 @@ SELECT ROW(1,2.5,'this is a test'); <replaceable>rowvalue</replaceable><literal>.*</literal>, which will be expanded to a list of the elements of the row value, just as occurs when the <literal>.*</> syntax is used at the top level - of a <command>SELECT</> list. For example, if table <literal>t</> has + of a <command>SELECT</> list (see <xref linkend="rowtypes-usage">). + For example, if table <literal>t</> has columns <literal>f1</> and <literal>f2</>, these are the same: <programlisting> SELECT ROW(t.*, 42) FROM t; @@ -2302,9 +2312,9 @@ SELECT ROW(t.f1, t.f2, 42) FROM t; <note> <para> Before <productname>PostgreSQL</productname> 8.2, the - <literal>.*</literal> syntax was not expanded, so that writing - <literal>ROW(t.*, 42)</> created a two-field row whose first field - was another row value. The new behavior is usually more useful. + <literal>.*</literal> syntax was not expanded in row constructors, so + that writing <literal>ROW(t.*, 42)</> created a two-field row whose first + field was another row value. The new behavior is usually more useful. If you need the old behavior of nested row values, write the inner row value without <literal>.*</literal>, for instance <literal>ROW(t, 42)</>. diff --git a/doc/src/sgml/test-decoding.sgml b/doc/src/sgml/test-decoding.sgml index 23cdfe35f8..4f4fd41e32 100644 --- a/doc/src/sgml/test-decoding.sgml +++ b/doc/src/sgml/test-decoding.sgml @@ -25,7 +25,7 @@ <programlisting> postgres=# SELECT * FROM pg_logical_slot_get_changes('test_slot', NULL, NULL, 'include-xids', '0'); - location | xid | data + lsn | xid | data -----------+-----+-------------------------------------------------- 0/16D30F8 | 691 | BEGIN 0/16D32A0 | 691 | table public.data: INSERT: id[int4]:2 data[text]:'arg' diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml index be5974a4ff..fe630a66b3 100644 --- a/doc/src/sgml/textsearch.sgml +++ b/doc/src/sgml/textsearch.sgml @@ -264,7 +264,7 @@ SELECT 'fat & cow'::tsquery @@ 'a fat cat sat on a mat and ate a fat rat'::t text, any more than a <type>tsvector</type> is. A <type>tsquery</type> contains search terms, which must be already-normalized lexemes, and may combine multiple terms using AND, OR, NOT, and FOLLOWED BY operators. - (For details see <xref linkend="datatype-tsquery">.) There are + (For syntax details see <xref linkend="datatype-tsquery">.) There are functions <function>to_tsquery</>, <function>plainto_tsquery</>, and <function>phraseto_tsquery</> that are helpful in converting user-written text into a proper @@ -323,6 +323,8 @@ text @@ text at least one of its arguments must appear, while the <literal>!</> (NOT) operator specifies that its argument must <emphasis>not</> appear in order to have a match. + For example, the query <literal>fat & ! rat</> matches documents that + contain <literal>fat</> but not <literal>rat</>. </para> <para> @@ -377,6 +379,28 @@ SELECT phraseto_tsquery('the cats ate the rats'); then <literal>&</literal>, then <literal><-></literal>, and <literal>!</literal> most tightly. </para> + + <para> + It's worth noticing that the AND/OR/NOT operators mean something subtly + different when they are within the arguments of a FOLLOWED BY operator + than when they are not, because within FOLLOWED BY the exact position of + the match is significant. For example, normally <literal>!x</> matches + only documents that do not contain <literal>x</> anywhere. + But <literal>!x <-> y</> matches <literal>y</> if it is not + immediately after an <literal>x</>; an occurrence of <literal>x</> + elsewhere in the document does not prevent a match. Another example is + that <literal>x & y</> normally only requires that <literal>x</> + and <literal>y</> both appear somewhere in the document, but + <literal>(x & y) <-> z</> requires <literal>x</> + and <literal>y</> to match at the same place, immediately before + a <literal>z</>. Thus this query behaves differently from + <literal>x <-> z & y <-> z</>, which will match a + document containing two separate sequences <literal>x z</> and + <literal>y z</>. (This specific query is useless as written, + since <literal>x</> and <literal>y</> could not match at the same place; + but with more complex situations such as prefix-match patterns, a query + of this form could be useful.) + </para> </sect2> <sect2 id="textsearch-intro-configurations"> @@ -1290,19 +1314,7 @@ query.', <para> <function>ts_headline</> uses the original document, not a <type>tsvector</type> summary, so it can be slow and should be used with - care. A typical mistake is to call <function>ts_headline</function> for - <emphasis>every</emphasis> matching document when only ten documents are - to be shown. <acronym>SQL</acronym> subqueries can help; here is an - example: - -<programlisting> -SELECT id, ts_headline(body, q), rank -FROM (SELECT id, body, q, ts_rank_cd(ti, q) AS rank - FROM apod, to_tsquery('stars') q - WHERE ti @@ q - ORDER BY rank DESC - LIMIT 10) AS foo; -</programlisting> + care. </para> </sect2> @@ -3622,10 +3634,10 @@ SELECT plainto_tsquery('supernovae stars'); </para> <para> - The optional parameter <literal>PATTERN</literal> can be the name of + The optional parameter <replaceable>PATTERN</replaceable> can be the name of a text search object, optionally schema-qualified. If - <literal>PATTERN</literal> is omitted then information about all - visible objects will be displayed. <literal>PATTERN</literal> can be a + <replaceable>PATTERN</replaceable> is omitted then information about all + visible objects will be displayed. <replaceable>PATTERN</replaceable> can be a regular expression and can provide <emphasis>separate</emphasis> patterns for the schema and object names. The following examples illustrate this: @@ -3852,87 +3864,4 @@ Parser: "pg_catalog.default" </sect1> - <sect1 id="textsearch-migration"> - <title>Migration from Pre-8.3 Text Search</title> - - <para> - Applications that use the <xref linkend="tsearch2"> - module for text searching will need some adjustments to work - with the - built-in features: - </para> - - <itemizedlist> - <listitem> - <para> - Some functions have been renamed or had small adjustments in their - argument lists, and all of them are now in the <literal>pg_catalog</> - schema, whereas in a previous installation they would have been in - <literal>public</> or another non-system schema. There is a new - version of <application>tsearch2</> - that provides a compatibility layer to solve most problems in this - area. - </para> - </listitem> - - <listitem> - <para> - The old <application>tsearch2</> functions and other objects - <emphasis>must</> be suppressed when loading <application>pg_dump</> - output from a pre-8.3 database. While many of them won't load anyway, - a few will and then cause problems. One simple way to deal with this - is to load the new <application>tsearch2</> module before restoring - the dump; then it will block the old objects from being loaded. - </para> - </listitem> - - <listitem> - <para> - Text search configuration setup is completely different now. - Instead of manually inserting rows into configuration tables, - search is configured through the specialized SQL commands shown - earlier in this chapter. There is no automated - support for converting an existing custom configuration for 8.3; - you're on your own here. - </para> - </listitem> - - <listitem> - <para> - Most types of dictionaries rely on some outside-the-database - configuration files. These are largely compatible with pre-8.3 - usage, but note the following differences: - - <itemizedlist spacing="compact" mark="bullet"> - <listitem> - <para> - Configuration files now must be placed in a single specified - directory (<filename>$SHAREDIR/tsearch_data</>), and must have - a specific extension depending on the type of file, as noted - previously in the descriptions of the various dictionary types. - This restriction was added to forestall security problems. - </para> - </listitem> - - <listitem> - <para> - Configuration files must be encoded in UTF-8 encoding, - regardless of what database encoding is used. - </para> - </listitem> - - <listitem> - <para> - In thesaurus configuration files, stop words must be marked with - <literal>?</>. - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - - </itemizedlist> - - </sect1> - </chapter> diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml index c1fa1ccaf6..ea29a09768 100644 --- a/doc/src/sgml/trigger.sgml +++ b/doc/src/sgml/trigger.sgml @@ -37,7 +37,8 @@ <para> A trigger is a specification that the database should automatically execute a particular function whenever a certain type of operation is - performed. Triggers can be attached to tables, views, and foreign tables. + performed. Triggers can be attached to tables (partitioned or not), + views, and foreign tables. </para> <para> @@ -115,14 +116,22 @@ Statement-level <literal>BEFORE</> triggers naturally fire before the statement starts to do anything, while statement-level <literal>AFTER</> triggers fire at the very end of the statement. These types of - triggers may be defined on tables or views. Row-level <literal>BEFORE</> - triggers fire immediately before a particular row is operated on, - while row-level <literal>AFTER</> triggers fire at the end of the - statement (but before any statement-level <literal>AFTER</> triggers). - These types of triggers may only be defined on tables and foreign tables. - Row-level <literal>INSTEAD OF</> triggers may only be defined on views, - and fire immediately as each row in the view is identified as needing to - be operated on. + triggers may be defined on tables, views, or foreign tables. Row-level + <literal>BEFORE</> triggers fire immediately before a particular row is + operated on, while row-level <literal>AFTER</> triggers fire at the end of + the statement (but before any statement-level <literal>AFTER</> triggers). + These types of triggers may only be defined on non-partitioned tables and + foreign tables. Row-level <literal>INSTEAD OF</> triggers may only be + defined on views, and fire immediately as each row in the view is + identified as needing to be operated on. + </para> + + <para> + A statement that targets a parent table in an inheritance or partitioning + hierarchy does not cause the statement-level triggers of affected child + tables to be fired; only the parent table's statement-level triggers are + fired. However, row-level triggers of any affected child tables will be + fired. </para> <para> @@ -399,6 +408,11 @@ <secondary>in C</secondary> </indexterm> + <indexterm> + <primary>transition tables</primary> + <secondary>referencing from C trigger</secondary> + </indexterm> + <para> This section describes the low-level details of the interface to a trigger function. This information is only needed when writing @@ -442,14 +456,16 @@ CALLED_AS_TRIGGER(fcinfo) <programlisting> typedef struct TriggerData { - NodeTag type; - TriggerEvent tg_event; - Relation tg_relation; - HeapTuple tg_trigtuple; - HeapTuple tg_newtuple; - Trigger *tg_trigger; - Buffer tg_trigtuplebuf; - Buffer tg_newtuplebuf; + NodeTag type; + TriggerEvent tg_event; + Relation tg_relation; + HeapTuple tg_trigtuple; + HeapTuple tg_newtuple; + Trigger *tg_trigger; + Buffer tg_trigtuplebuf; + Buffer tg_newtuplebuf; + Tuplestorestate *tg_oldtable; + Tuplestorestate *tg_newtable; } TriggerData; </programlisting> @@ -633,6 +649,8 @@ typedef struct Trigger int16 *tgattr; char **tgargs; char *tgqual; + char *tgoldtable; + char *tgnewtable; } Trigger; </programlisting> @@ -666,10 +684,39 @@ typedef struct Trigger </listitem> </varlistentry> + <varlistentry> + <term><structfield>tg_oldtable</></term> + <listitem> + <para> + A pointer to a structure of type <structname>Tuplestorestate</structname> + containing zero or more rows in the format specified by + <structfield>tg_relation</structfield>, or a <symbol>NULL</> pointer + if there is no <literal>OLD TABLE</literal> transition relation. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><structfield>tg_newtable</></term> + <listitem> + <para> + A pointer to a structure of type <structname>Tuplestorestate</structname> + containing zero or more rows in the format specified by + <structfield>tg_relation</structfield>, or a <symbol>NULL</> pointer + if there is no <literal>NEW TABLE</literal> transition relation. + </para> + </listitem> + </varlistentry> + </variablelist> </para> <para> + To allow queries issued through SPI to reference transition tables, see + <xref linkend="spi-spi-register-trigger-data">. + </para> + + <para> A trigger function must return either a <structname>HeapTuple</> pointer or a <symbol>NULL</> pointer (<emphasis>not</> an SQL null value, that is, do not set <parameter>isNull</parameter> true). @@ -709,6 +756,7 @@ CREATE TABLE ttest ( This is the source code of the trigger function: <programlisting><![CDATA[ #include "postgres.h" +#include "fmgr.h" #include "executor/spi.h" /* this is what you need to work with SPI */ #include "commands/trigger.h" /* ... triggers ... */ #include "utils/rel.h" /* ... and relations */ diff --git a/doc/src/sgml/tsearch2.sgml b/doc/src/sgml/tsearch2.sgml deleted file mode 100644 index 192eccd732..0000000000 --- a/doc/src/sgml/tsearch2.sgml +++ /dev/null @@ -1,203 +0,0 @@ -<!-- doc/src/sgml/tsearch2.sgml --> - -<sect1 id="tsearch2" xreflabel="tsearch2"> - <title>tsearch2</title> - - <indexterm zone="tsearch2"> - <primary>tsearch2</primary> - </indexterm> - - <para> - The <application>tsearch2</> module provides backwards-compatible - text search functionality for applications that used - <application>tsearch2</> before text searching was integrated - into core <productname>PostgreSQL</productname> in release 8.3. - </para> - - <sect2> - <title>Portability Issues</title> - - <para> - Although the built-in text search features were based on - <application>tsearch2</> and are largely similar to it, - there are numerous small differences that will create portability - issues for existing applications: - </para> - - <itemizedlist mark="bullet"> - <listitem> - <para> - Some functions' names were changed, for example <function>rank</> - to <function>ts_rank</>. - The replacement <literal>tsearch2</literal> module - provides aliases having the old names. - </para> - </listitem> - - <listitem> - <para> - The built-in text search data types and functions all exist within - the system schema <literal>pg_catalog</>. In an installation using - <application>tsearch2</>, these objects would usually have been in - the <literal>public</> schema, though some users chose to place them - in a separate schema of their own. Explicitly schema-qualified - references to the objects will therefore fail in either case. - The replacement <literal>tsearch2</literal> module - provides alias objects that are stored in <literal>public</> - (or another schema if necessary) so that such references will still work. - </para> - </listitem> - - <listitem> - <para> - There is no concept of a <quote>current parser</> or <quote>current - dictionary</> in the built-in text search features, only of a current - search configuration (set by the <varname>default_text_search_config</> - parameter). While the current parser and current dictionary were used - only by functions intended for debugging, this might still pose - a porting obstacle in some cases. - The replacement <literal>tsearch2</literal> module emulates these - additional state variables and provides backwards-compatible functions - for setting and retrieving them. - </para> - </listitem> - </itemizedlist> - - <para> - There are some issues that are not addressed by the replacement - <literal>tsearch2</literal> module, and will therefore require - application code changes in any case: - </para> - - <itemizedlist mark="bullet"> - <listitem> - <para> - The old <function>tsearch2</> trigger function allowed items in its - argument list to be names of functions to be invoked on the text data - before it was converted to <type>tsvector</> format. This was removed - as being a security hole, since it was not possible to guarantee that - the function invoked was the one intended. The recommended approach - if the data must be massaged before being indexed is to write a custom - trigger that does the work for itself. - </para> - </listitem> - - <listitem> - <para> - Text search configuration information has been moved into core - system catalogs that are noticeably different from the tables used - by <application>tsearch2</>. Any applications that examined - or modified those tables will need adjustment. - </para> - </listitem> - - <listitem> - <para> - If an application used any custom text search configurations, - those will need to be set up in the core - catalogs using the new text search configuration SQL commands. - The replacement <literal>tsearch2</literal> module offers a little - bit of support for this by making it possible to load an old set - of <application>tsearch2</> configuration tables into - <productname>PostgreSQL</productname> 8.3. (Without the module, - it is not possible to load the configuration data because values in the - <type>regprocedure</> columns cannot be resolved to functions.) - While those configuration tables won't actually <emphasis>do</> - anything, at least their contents will be available to be consulted - while setting up an equivalent custom configuration in 8.3. - </para> - </listitem> - - <listitem> - <para> - The old <function>reset_tsearch()</> and <function>get_covers()</> - functions are not supported. - </para> - </listitem> - - <listitem> - <para> - The replacement <literal>tsearch2</literal> module does not define - any alias operators, relying entirely on the built-in ones. - This would only pose an issue if an application used explicitly - schema-qualified operator names, which is very uncommon. - </para> - </listitem> - </itemizedlist> - - </sect2> - - <sect2> - <title>Converting a pre-8.3 Installation</title> - - <para> - The recommended way to update a pre-8.3 installation that uses - <application>tsearch2</> is: - </para> - - <procedure> - <step> - <para> - Make a dump from the old installation in the usual way, - but be sure not to use <literal>-c</> (<literal>--clean</>) - option of <application>pg_dump</> or <application>pg_dumpall</>. - </para> - </step> - - <step> - <para> - In the new installation, create empty database(s) and install - the replacement <literal>tsearch2</literal> module into each - database that will use text search. This must be done - <emphasis>before</> loading the dump data! If your old installation - had the <application>tsearch2</> objects in a schema other - than <literal>public</>, be sure to adjust the - <command>CREATE EXTENSION</> command so that the replacement - objects are created in that same schema. - </para> - </step> - - <step> - <para> - Load the dump data. There will be quite a few errors reported - due to failure to recreate the original <application>tsearch2</> - objects. These errors can be ignored, but this means you cannot - restore the dump in a single transaction (eg, you cannot use - <application>pg_restore</>'s <option>-1</> switch). - </para> - </step> - - <step> - <para> - Examine the contents of the restored <application>tsearch2</> - configuration tables (<structname>pg_ts_cfg</> and so on), and - create equivalent built-in text search configurations as needed. - You may drop the old configuration tables once you've extracted - all the useful information from them. - </para> - </step> - - <step> - <para> - Test your application. - </para> - </step> - </procedure> - - <para> - At a later time you may wish to rename application references - to the alias text search objects, so that you can eventually - uninstall the replacement <literal>tsearch2</literal> module. - </para> - - </sect2> - - <sect2> - <title>References</title> - <para> - Tsearch2 Development Site - <ulink url="http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/"></ulink> - </para> - </sect2> - -</sect1> diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml index c031c01ed3..63d41f03f3 100644 --- a/doc/src/sgml/typeconv.sgml +++ b/doc/src/sgml/typeconv.sgml @@ -984,7 +984,8 @@ domain's base type for all subsequent steps. <para> If all inputs are of type <type>unknown</type>, resolve as type <type>text</type> (the preferred type of the string category). -Otherwise, <type>unknown</type> inputs are ignored. +Otherwise, <type>unknown</type> inputs are ignored for the purposes +of the remaining rules. </para> </step> @@ -1076,6 +1077,53 @@ but <type>integer</> can be implicitly cast to <type>real</>, the union result type is resolved as <type>real</>. </para> </example> +</sect1> + +<sect1 id="typeconv-select"> +<title><literal>SELECT</literal> Output Columns</title> + +<indexterm zone="typeconv-select"> + <primary>SELECT</primary> + <secondary>determination of result type</secondary> +</indexterm> + +<para> +The rules given in the preceding sections will result in assignment +of non-<type>unknown</> data types to all expressions in a SQL query, +except for unspecified-type literals that appear as simple output +columns of a <command>SELECT</> command. For example, in + +<screen> +SELECT 'Hello World'; +</screen> + +there is nothing to identify what type the string literal should be +taken as. In this situation <productname>PostgreSQL</> will fall back +to resolving the literal's type as <type>text</>. +</para> + +<para> +When the <command>SELECT</> is one arm of a <literal>UNION</> +(or <literal>INTERSECT</> or <literal>EXCEPT</>) construct, or when it +appears within <command>INSERT ... SELECT</>, this rule is not applied +since rules given in preceding sections take precedence. The type of an +unspecified-type literal can be taken from the other <literal>UNION</> arm +in the first case, or from the destination column in the second case. +</para> + +<para> +<literal>RETURNING</> lists are treated the same as <command>SELECT</> +output lists for this purpose. +</para> + +<note> + <para> + Prior to <productname>PostgreSQL</> 10, this rule did not exist, and + unspecified-type literals in a <command>SELECT</> output list were + left as type <type>unknown</>. That had assorted bad consequences, + so it's been changed. + </para> +</note> </sect1> </chapter> diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml index 7eaefe58c2..914f1505ab 100644 --- a/doc/src/sgml/user-manag.sgml +++ b/doc/src/sgml/user-manag.sgml @@ -516,14 +516,50 @@ DROP ROLE doomed_role; </thead> <tbody> <row> + <entry>pg_read_all_settings</entry> + <entry>Read all configuration variables, even those normally visible only to + superusers.</entry> + </row> + <row> + <entry>pg_read_all_stats</entry> + <entry>Read all pg_stat_* views and use various statistics related extensions, + even those normally visible only to superusers.</entry> + </row> + <row> + <entry>pg_stat_scan_tables</entry> + <entry>Execute monitoring functions that may take AccessShareLocks on tables, + potentially for a long time.</entry> + </row> + <row> <entry>pg_signal_backend</entry> <entry>Send signals to other backends (eg: cancel query, terminate).</entry> </row> + <row> + <entry>pg_monitor</entry> + <entry>Read/execute various monitoring views and functions. + This role is a member of <literal>pg_read_all_settings</literal>, + <literal>pg_read_all_stats</literal> and + <literal>pg_stat_scan_tables</literal>.</entry> + </row> </tbody> </tgroup> </table> <para> + The <literal>pg_monitor</literal>, <literal>pg_read_all_settings</literal>, + <literal>pg_read_all_stats</literal> and <literal>pg_stat_scan_tables</literal> + roles are intended to allow administrators to easily configure a role for the + purpose of monitoring the database server. They grant a set of common privileges + allowing the role to read various useful configuration settings, statistics and + other system information normally restricted to superusers. + </para> + + <para> + Care should be taken when granting these roles to ensure they are only used where + needed to perform the desired monitoring. + </para> + + <para> Administrators can grant access to these roles to users using the GRANT command: diff --git a/doc/src/sgml/uuid-ossp.sgml b/doc/src/sgml/uuid-ossp.sgml index e275febe4e..227d4a839c 100644 --- a/doc/src/sgml/uuid-ossp.sgml +++ b/doc/src/sgml/uuid-ossp.sgml @@ -169,7 +169,7 @@ SELECT uuid_generate_v3(uuid_ns_url(), 'http://www.postgresql.org'); platforms. <filename>uuid-ossp</> can now be built without the OSSP library on some platforms. On FreeBSD, NetBSD, and some other BSD-derived platforms, suitable UUID creation functions are included in the - core <filename>libc</> library. On Linux, OS X, and some other + core <filename>libc</> library. On Linux, macOS, and some other platforms, suitable functions are provided in the <filename>libuuid</> library, which originally came from the <literal>e2fsprogs</> project (though on modern Linux it is considered part diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml index 308c8fd2e6..fe3bc69bd2 100644 --- a/doc/src/sgml/wal.sgml +++ b/doc/src/sgml/wal.sgml @@ -115,7 +115,7 @@ <listitem> <para> - On <productname>OS X</productname>, write caching can be prevented by + On <productname>macOS</productname>, write caching can be prevented by setting <varname>wal_sync_method</> to <literal>fsync_writethrough</>. </para> </listitem> @@ -201,7 +201,7 @@ </listitem> <listitem> <para> - Internal data structures such as <filename>pg_clog</filename>, <filename>pg_subtrans</filename>, <filename>pg_multixact</filename>, + Internal data structures such as <filename>pg_xact</filename>, <filename>pg_subtrans</filename>, <filename>pg_multixact</filename>, <filename>pg_serial</filename>, <filename>pg_notify</filename>, <filename>pg_stat</filename>, <filename>pg_snapshots</filename> are not directly checksummed, nor are pages protected by full page writes. However, where such data structures are persistent, WAL records are written that allow @@ -557,7 +557,7 @@ </para> <para> - The number of WAL segment files in <filename>pg_xlog</> directory depends on + The number of WAL segment files in <filename>pg_wal</> directory depends on <varname>min_wal_size</>, <varname>max_wal_size</> and the amount of WAL generated in previous checkpoint cycles. When old log segment files are no longer needed, they are removed or recycled (that is, @@ -569,7 +569,7 @@ removes the rest. The estimate is based on a moving average of the number of WAL files used in previous checkpoint cycles. The moving average is increased immediately if the actual usage exceeds the estimate, so it - accommodates peak usage rather average usage to some extent. + accommodates peak usage rather than average usage to some extent. <varname>min_wal_size</> puts a minimum on the amount of WAL files recycled for future usage; that much WAL is always recycled for future use, even if the system is idle and the WAL usage estimate suggests that little @@ -582,7 +582,7 @@ kept at all times. Also, if WAL archiving is used, old segments can not be removed or recycled until they are archived. If WAL archiving cannot keep up with the pace that WAL is generated, or if <varname>archive_command</varname> - fails repeatedly, old WAL files will accumulate in <filename>pg_xlog</> + fails repeatedly, old WAL files will accumulate in <filename>pg_wal</> until the situation is resolved. A slow or failed standby server that uses a replication slot will have the same effect (see <xref linkend="streaming-replication-slots">). @@ -594,7 +594,7 @@ which are similar to checkpoints in normal operation: the server forces all its state to disk, updates the <filename>pg_control</> file to indicate that the already-processed WAL data need not be scanned again, - and then recycles any old log segment files in the <filename>pg_xlog</> + and then recycles any old log segment files in the <filename>pg_wal</> directory. Restartpoints can't be performed more frequently than checkpoints in the master because restartpoints can only be performed at checkpoint records. @@ -724,6 +724,10 @@ <sect1 id="wal-internals"> <title>WAL Internals</title> + <indexterm zone="wal-internals"> + <primary>LSN</primary> + </indexterm> + <para> <acronym>WAL</acronym> is automatically enabled; no action is required from the administrator except ensuring that the @@ -733,8 +737,20 @@ </para> <para> + <acronym>WAL</acronym> records are appended to the <acronym>WAL</acronym> + logs as each new record is written. The insert position is described by + a Log Sequence Number (<acronym>LSN</acronym>) that is a byte offset into + the logs, increasing monotonically with each new record. + <acronym>LSN</acronym> values are returned as the datatype + <link linkend="datatype-pg-lsn"><type>pg_lsn</></link>. Values can be + compared to calculate the volume of <acronym>WAL</acronym> data that + separates them, so they are used to measure the progress of replication + and recovery. + </para> + + <para> <acronym>WAL</acronym> logs are stored in the directory - <filename>pg_xlog</filename> under the data directory, as a set of + <filename>pg_wal</filename> under the data directory, as a set of segment files, normally each 16 MB in size (but the size can be changed by altering the <option>--with-wal-segsize</> configure option when building the server). Each segment is divided into pages, normally @@ -751,7 +767,7 @@ <para> It is advantageous if the log is located on a different disk from the main database files. This can be achieved by moving the - <filename>pg_xlog</filename> directory to another location (while the server + <filename>pg_wal</filename> directory to another location (while the server is shut down, of course) and creating a symbolic link from the original location in the main data directory to the new location. </para> @@ -775,7 +791,7 @@ <filename>pg_control</filename>. Therefore, at the start of recovery, the server first reads <filename>pg_control</filename> and then the checkpoint record; then it performs the REDO operation by - scanning forward from the log position indicated in the checkpoint + scanning forward from the log location indicated in the checkpoint record. Because the entire content of data pages is saved in the log on the first page modification after a checkpoint (assuming <xref linkend="guc-full-page-writes"> is not disabled), all pages diff --git a/doc/src/sgml/xaggr.sgml b/doc/src/sgml/xaggr.sgml index db5759ac63..dddbe2504a 100644 --- a/doc/src/sgml/xaggr.sgml +++ b/doc/src/sgml/xaggr.sgml @@ -678,7 +678,7 @@ if (AggCheckCallContext(fcinfo, NULL)) function, the first input must be a temporary state value and can therefore safely be modified in-place rather than allocating a new copy. - See <literal>int8inc()</> for an example. + See <function>int8inc()</> for an example. (This is the <emphasis>only</> case where it is safe for a function to modify a pass-by-reference input. In particular, final functions for normal aggregates must not @@ -687,6 +687,20 @@ if (AggCheckCallContext(fcinfo, NULL)) </para> <para> + The second argument of <function>AggCheckCallContext</> can be used to + retrieve the memory context in which aggregate state values are being kept. + This is useful for transition functions that wish to use <quote>expanded</> + objects (see <xref linkend="xtypes-toast">) as their state values. + On first call, the transition function should return an expanded object + whose memory context is a child of the aggregate state context, and then + keep returning the same expanded object on subsequent calls. See + <function>array_append()</> for an example. (<function>array_append()</> + is not the transition function of any built-in aggregate, but it is written + to behave efficiently when used as transition function of a custom + aggregate.) + </para> + + <para> Another support routine available to aggregate functions written in C is <function>AggGetAggref</>, which returns the <literal>Aggref</> parse node that defines the aggregate call. This is mainly useful diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index f9d923b949..bbe7475fb5 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -153,7 +153,7 @@ SELECT clean_emp(); <literal>CREATE TABLE foo (...); INSERT INTO foo VALUES(...);</literal> will not work as desired if packaged up into a single SQL function, since <structname>foo</> won't exist yet when the <command>INSERT</> - command is parsed. It's recommended to use <application>PL/PgSQL</> + command is parsed. It's recommended to use <application>PL/pgSQL</> instead of a SQL function in this type of situation. </para> </note> @@ -204,8 +204,8 @@ SELECT clean_emp(); <para> If an argument is of a composite type, then the dot notation, - e.g., <literal>argname.fieldname</literal> or - <literal>$1.fieldname</literal>, can be used to access attributes of the + e.g., <literal><replaceable>argname</>.<replaceable>fieldname</></literal> or + <literal>$1.<replaceable>fieldname</></literal>, can be used to access attributes of the argument. Again, you might need to qualify the argument's name with the function name to make the form with an argument name unambiguous. </para> @@ -394,8 +394,8 @@ SELECT name, double_salary(emp.*) AS dream <para> Notice the use of the syntax <literal>$1.salary</literal> to select one field of the argument row value. Also notice - how the calling <command>SELECT</> command uses <literal>*</> - to select + how the calling <command>SELECT</> command + uses <replaceable>table_name</><literal>.*</> to select the entire current row of a table as a composite value. The table row can alternatively be referenced using just the table name, like this: @@ -405,6 +405,8 @@ SELECT name, double_salary(emp) AS dream WHERE emp.cubicle ~= point '(2,1)'; </screen> but this usage is deprecated since it's easy to get confused. + (See <xref linkend="rowtypes-usage"> for details about these + two notations for the composite value of a table row.) </para> <para> @@ -479,7 +481,8 @@ $$ LANGUAGE SQL; </para> <para> - We could call this function directly in either of two ways: + We could call this function directly either by using it in + a value expression: <screen> SELECT new_emp(); @@ -487,7 +490,11 @@ SELECT new_emp(); new_emp -------------------------- (None,1000.0,25,"(2,2)") +</screen> + + or by calling it as a table function: +<screen> SELECT * FROM new_emp(); name | salary | age | cubicle @@ -524,11 +531,7 @@ LINE 1: SELECT new_emp().name; </para> <para> - Another option is to use - functional notation for extracting an attribute. The simple way - to explain this is that we can use the - notations <literal>attribute(table)</> and <literal>table.attribute</> - interchangeably. + Another option is to use functional notation for extracting an attribute: <screen> SELECT name(new_emp()); @@ -538,50 +541,10 @@ SELECT name(new_emp()); None </screen> -<screen> --- This is the same as: --- SELECT emp.name AS youngster FROM emp WHERE emp.age < 30; - -SELECT name(emp) AS youngster FROM emp WHERE age(emp) < 30; - - youngster ------------ - Sam - Andy -</screen> + As explained in <xref linkend="rowtypes-usage">, the field notation and + functional notation are equivalent. </para> - <tip> - <para> - The equivalence between functional notation and attribute notation - makes it possible to use functions on composite types to emulate - <quote>computed fields</>. - <indexterm> - <primary>computed field</primary> - </indexterm> - <indexterm> - <primary>field</primary> - <secondary>computed</secondary> - </indexterm> - For example, using the previous definition - for <literal>double_salary(emp)</>, we can write - -<screen> -SELECT emp.name, emp.double_salary FROM emp; -</screen> - - An application using this wouldn't need to be directly aware that - <literal>double_salary</> isn't a real column of the table. - (You can also emulate computed fields with views.) - </para> - - <para> - Because of this behavior, it's unwise to give a function that takes - a single composite-type argument the same name as any of the fields of - that composite type. - </para> - </tip> - <para> Another way to use a function returning a composite type is to pass the result to another function that accepts the correct row type as input: @@ -598,12 +561,6 @@ SELECT getname(new_emp()); (1 row) </screen> </para> - - <para> - Still another way to use a function that returns a composite type is to - call it as a table function, as described in <xref - linkend="xfunc-sql-table-functions">. - </para> </sect2> <sect2 id="xfunc-output-parameters"> @@ -1011,12 +968,11 @@ SELECT name, child FROM nodes, LATERAL listchildren(name) AS child; </para> <para> - Currently, functions returning sets can also be called in the select list + Functions returning sets can also be called in the select list of a query. For each row that the query - generates by itself, the function returning set is invoked, and an output - row is generated for each element of the function's result set. Note, - however, that this capability is deprecated and might be removed in future - releases. The previous example could also be done with queries like + generates by itself, the set-returning function is invoked, and an output + row is generated for each element of the function's result set. + The previous example could also be done with queries like these: <screen> @@ -1047,6 +1003,65 @@ SELECT name, listchildren(name) FROM nodes; the <literal>LATERAL</> syntax. </para> + <para> + If there is more than one set-returning function in the query's select + list, the behavior is similar to what you get from putting the functions + into a single <literal>LATERAL ROWS FROM( ... )</> <literal>FROM</>-clause + item. For each row from the underlying query, there is an output row + using the first result from each function, then an output row using the + second result, and so on. If some of the set-returning functions + produce fewer outputs than others, null values are substituted for the + missing data, so that the total number of rows emitted for one + underlying row is the same as for the set-returning function that + produced the most outputs. Thus the set-returning functions + run <quote>in lockstep</> until they are all exhausted, and then + execution continues with the next underlying row. + </para> + + <para> + Set-returning functions can be nested in a select list, although that is + not allowed in <literal>FROM</>-clause items. In such cases, each level + of nesting is treated separately, as though it were + a separate <literal>LATERAL ROWS FROM( ... )</> item. For example, in +<programlisting> +SELECT srf1(srf2(x), srf3(y)), srf4(srf5(z)) FROM tab; +</programlisting> + the set-returning functions <function>srf2</>, <function>srf3</>, + and <function>srf5</> would be run in lockstep for each row + of <structname>tab</>, and then <function>srf1</> and <function>srf4</> + would be applied in lockstep to each row produced by the lower + functions. + </para> + + <para> + This behavior also means that set-returning functions will be evaluated + even when it might appear that they should be skipped because of a + conditional-evaluation construct, such as <literal>CASE</> + or <literal>COALESCE</>. For example, consider +<programlisting> +SELECT x, CASE WHEN x > 0 THEN generate_series(1, 5) ELSE 0 END FROM tab; +</programlisting> + It might seem that this should produce five repetitions of input + rows that have <literal>x > 0</>, and a single repetition of those + that do not; but actually it will produce five repetitions of every + input row. This is because <function>generate_series()</> is run first, + and then the <literal>CASE</> expression is applied to its result rows. + The behavior is thus comparable to +<programlisting> +SELECT x, CASE WHEN x > 0 THEN g ELSE 0 END + FROM tab, LATERAL generate_series(1,5) AS g; +</programlisting> + It would be exactly the same, except that in this specific example, + the planner could choose to put <structname>g</> on the outside of the + nestloop join, since <structname>g</> has no actual lateral dependency + on <structname>tab</>. That would result in a different output row + order. Set-returning functions in the select list are always evaluated + as though they are on the inside of a nestloop join with the rest of + the <literal>FROM</> clause, so that the function(s) are run to + completion before the next row from the <literal>FROM</> clause is + considered. + </para> + <note> <para> If a function's last command is <command>INSERT</>, <command>UPDATE</>, @@ -1061,14 +1076,19 @@ SELECT name, listchildren(name) FROM nodes; <note> <para> - The key problem with using set-returning functions in the select list, - rather than the <literal>FROM</> clause, is that putting more than one - set-returning function in the same select list does not behave very - sensibly. (What you actually get if you do so is a number of output - rows equal to the least common multiple of the numbers of rows produced - by each set-returning function.) The <literal>LATERAL</> syntax - produces less surprising results when calling multiple set-returning - functions, and should usually be used instead. + Before <productname>PostgreSQL</> 10, putting more than one + set-returning function in the same select list did not behave very + sensibly unless they always produced equal numbers of rows. Otherwise, + what you got was a number of output rows equal to the least common + multiple of the numbers of rows produced by the set-returning + functions. Also, nested set-returning functions did not work as + described above; instead, a set-returning function could have at most + one set-returning argument, and each nest of set-returning functions + was run independently. The behavior for conditional execution + (set-returning functions inside <literal>CASE</> etc) was different too. + Use of the <literal>LATERAL</> syntax is recommended when writing + queries that need to work in older <productname>PostgreSQL</> versions, + because that will give consistent results across different versions. </para> </note> </sect2> @@ -1311,12 +1331,15 @@ CREATE FUNCTION test(smallint, double precision) RETURNS ... <para> A function that takes a single argument of a composite type should generally not have the same name as any attribute (field) of that type. - Recall that <literal>attribute(table)</literal> is considered equivalent - to <literal>table.attribute</literal>. In the case that there is an + Recall that <literal><replaceable>attribute</>(<replaceable>table</>)</literal> + is considered equivalent + to <literal><replaceable>table</>.<replaceable>attribute</></literal>. + In the case that there is an ambiguity between a function on a composite type and an attribute of the composite type, the attribute will always be used. It is possible to override that choice by schema-qualifying the function name - (that is, <literal>schema.func(table)</literal>) but it's better to + (that is, <literal><replaceable>schema</>.<replaceable>func</>(<replaceable>table</>) + </literal>) but it's better to avoid the problem by not choosing conflicting names. </para> @@ -1593,14 +1616,10 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision </para> <para> - Two different calling conventions are currently used for C functions. - The newer <quote>version 1</quote> calling convention is indicated by writing - a <literal>PG_FUNCTION_INFO_V1()</literal> macro call for the function, - as illustrated below. Lack of such a macro indicates an old-style - (<quote>version 0</quote>) function. The language name specified in <command>CREATE FUNCTION</command> - is <literal>C</literal> in either case. Old-style functions are now deprecated - because of portability problems and lack of functionality, but they - are still supported for compatibility reasons. + Currently only one calling convention is used for C functions + (<quote>version 1</quote>). Support for that calling convention is + indicated by writing a <literal>PG_FUNCTION_INFO_V1()</literal> macro + call for the function, as illustrated below. </para> <sect2 id="xfunc-c-dynload"> @@ -2121,160 +2140,6 @@ memcpy(destination->data, buffer, 40); </sect2> <sect2> - <title>Version 0 Calling Conventions</title> - - <para> - We present the <quote>old style</quote> calling convention first — although - this approach is now deprecated, it's easier to get a handle on - initially. In the version-0 method, the arguments and result - of the C function are just declared in normal C style, but being - careful to use the C representation of each SQL data type as shown - above. - </para> - - <para> - Here are some examples: - -<programlisting><![CDATA[ -#include "postgres.h" -#include <string.h> -#include "utils/geo_decls.h" - -#ifdef PG_MODULE_MAGIC -PG_MODULE_MAGIC; -#endif - -/* by value */ - -int -add_one(int arg) -{ - return arg + 1; -} - -/* by reference, fixed length */ - -float8 * -add_one_float8(float8 *arg) -{ - float8 *result = (float8 *) palloc(sizeof(float8)); - - *result = *arg + 1.0; - - return result; -} - -Point * -makepoint(Point *pointx, Point *pointy) -{ - Point *new_point = (Point *) palloc(sizeof(Point)); - - new_point->x = pointx->x; - new_point->y = pointy->y; - - return new_point; -} - -/* by reference, variable length */ - -text * -copytext(text *t) -{ - /* - * VARSIZE is the total size of the struct in bytes. - */ - text *new_t = (text *) palloc(VARSIZE(t)); - SET_VARSIZE(new_t, VARSIZE(t)); - /* - * VARDATA is a pointer to the data region of the struct. - */ - memcpy((void *) VARDATA(new_t), /* destination */ - (void *) VARDATA(t), /* source */ - VARSIZE(t) - VARHDRSZ); /* how many bytes */ - return new_t; -} - -text * -concat_text(text *arg1, text *arg2) -{ - int32 new_text_size = VARSIZE(arg1) + VARSIZE(arg2) - VARHDRSZ; - text *new_text = (text *) palloc(new_text_size); - - SET_VARSIZE(new_text, new_text_size); - memcpy(VARDATA(new_text), VARDATA(arg1), VARSIZE(arg1) - VARHDRSZ); - memcpy(VARDATA(new_text) + (VARSIZE(arg1) - VARHDRSZ), - VARDATA(arg2), VARSIZE(arg2) - VARHDRSZ); - return new_text; -} -]]> -</programlisting> - </para> - - <para> - Supposing that the above code has been prepared in file - <filename>funcs.c</filename> and compiled into a shared object, - we could define the functions to <productname>PostgreSQL</productname> - with commands like this: - -<programlisting> -CREATE FUNCTION add_one(integer) RETURNS integer - AS '<replaceable>DIRECTORY</replaceable>/funcs', 'add_one' - LANGUAGE C STRICT; - --- note overloading of SQL function name "add_one" -CREATE FUNCTION add_one(double precision) RETURNS double precision - AS '<replaceable>DIRECTORY</replaceable>/funcs', 'add_one_float8' - LANGUAGE C STRICT; - -CREATE FUNCTION makepoint(point, point) RETURNS point - AS '<replaceable>DIRECTORY</replaceable>/funcs', 'makepoint' - LANGUAGE C STRICT; - -CREATE FUNCTION copytext(text) RETURNS text - AS '<replaceable>DIRECTORY</replaceable>/funcs', 'copytext' - LANGUAGE C STRICT; - -CREATE FUNCTION concat_text(text, text) RETURNS text - AS '<replaceable>DIRECTORY</replaceable>/funcs', 'concat_text' - LANGUAGE C STRICT; -</programlisting> - </para> - - <para> - Here, <replaceable>DIRECTORY</replaceable> stands for the - directory of the shared library file (for instance the - <productname>PostgreSQL</productname> tutorial directory, which - contains the code for the examples used in this section). - (Better style would be to use just <literal>'funcs'</> in the - <literal>AS</> clause, after having added - <replaceable>DIRECTORY</replaceable> to the search path. In any - case, we can omit the system-specific extension for a shared - library, commonly <literal>.so</literal> or - <literal>.sl</literal>.) - </para> - - <para> - Notice that we have specified the functions as <quote>strict</quote>, - meaning that - the system should automatically assume a null result if any input - value is null. By doing this, we avoid having to check for null inputs - in the function code. Without this, we'd have to check for null values - explicitly, by checking for a null pointer for each - pass-by-reference argument. (For pass-by-value arguments, we don't - even have a way to check!) - </para> - - <para> - Although this calling convention is simple to use, - it is not very portable; on some architectures there are problems - with passing data types that are smaller than <type>int</type> this way. Also, there is - no simple way to return a null result, nor to cope with null arguments - in any way other than making the function strict. The version-1 - convention, presented next, overcomes these objections. - </para> - </sect2> - - <sect2> <title>Version 1 Calling Conventions</title> <para> @@ -2299,8 +2164,10 @@ PG_FUNCTION_INFO_V1(funcname); <para> In a version-1 function, each actual argument is fetched using a <function>PG_GETARG_<replaceable>xxx</replaceable>()</function> - macro that corresponds to the argument's data type, and the - result is returned using a + macro that corresponds to the argument's data type. In non-strict + functions there needs to be a previous check about argument null-ness + using <function>PG_ARGNULL_<replaceable>xxx</replaceable>()</function>. + The result is returned using a <function>PG_RETURN_<replaceable>xxx</replaceable>()</function> macro for the return type. <function>PG_GETARG_<replaceable>xxx</replaceable>()</function> @@ -2311,7 +2178,8 @@ PG_FUNCTION_INFO_V1(funcname); </para> <para> - Here we show the same functions as above, coded in version-1 style: + Here are some examples using the version-1 calling convention: + </para> <programlisting><![CDATA[ #include "postgres.h" @@ -2371,18 +2239,23 @@ PG_FUNCTION_INFO_V1(copytext); Datum copytext(PG_FUNCTION_ARGS) { - text *t = PG_GETARG_TEXT_P(0); + text *t = PG_GETARG_TEXT_PP(0); + /* - * VARSIZE is the total size of the struct in bytes. + * VARSIZE_ANY_EXHDR is the size of the struct in bytes, minus the + * VARHDRSZ or VARHDRSZ_SHORT of its header. Construct the copy with a + * full-length header. */ - text *new_t = (text *) palloc(VARSIZE(t)); - SET_VARSIZE(new_t, VARSIZE(t)); + text *new_t = (text *) palloc(VARSIZE_ANY_EXHDR(t) + VARHDRSZ); + SET_VARSIZE(new_t, VARSIZE_ANY_EXHDR(t) + VARHDRSZ); + /* - * VARDATA is a pointer to the data region of the struct. + * VARDATA is a pointer to the data region of the new struct. The source + * could be a short datum, so retrieve its data through VARDATA_ANY. */ memcpy((void *) VARDATA(new_t), /* destination */ - (void *) VARDATA(t), /* source */ - VARSIZE(t) - VARHDRSZ); /* how many bytes */ + (void *) VARDATA_ANY(t), /* source */ + VARSIZE_ANY_EXHDR(t)); /* how many bytes */ PG_RETURN_TEXT_P(new_t); } @@ -2391,40 +2264,82 @@ PG_FUNCTION_INFO_V1(concat_text); Datum concat_text(PG_FUNCTION_ARGS) { - text *arg1 = PG_GETARG_TEXT_P(0); - text *arg2 = PG_GETARG_TEXT_P(1); - int32 new_text_size = VARSIZE(arg1) + VARSIZE(arg2) - VARHDRSZ; + text *arg1 = PG_GETARG_TEXT_PP(0); + text *arg2 = PG_GETARG_TEXT_PP(1); + int32 arg1_size = VARSIZE_ANY_EXHDR(arg1); + int32 arg2_size = VARSIZE_ANY_EXHDR(arg2); + int32 new_text_size = arg1_size + arg2_size + VARHDRSZ; text *new_text = (text *) palloc(new_text_size); SET_VARSIZE(new_text, new_text_size); - memcpy(VARDATA(new_text), VARDATA(arg1), VARSIZE(arg1) - VARHDRSZ); - memcpy(VARDATA(new_text) + (VARSIZE(arg1) - VARHDRSZ), - VARDATA(arg2), VARSIZE(arg2) - VARHDRSZ); + memcpy(VARDATA(new_text), VARDATA_ANY(arg1), arg1_size); + memcpy(VARDATA(new_text) + arg1_size, VARDATA_ANY(arg2), arg2_size); PG_RETURN_TEXT_P(new_text); } ]]> </programlisting> + + <para> + Supposing that the above code has been prepared in file + <filename>funcs.c</filename> and compiled into a shared object, + we could define the functions to <productname>PostgreSQL</productname> + with commands like this: </para> +<programlisting> +CREATE FUNCTION add_one(integer) RETURNS integer + AS '<replaceable>DIRECTORY</replaceable>/funcs', 'add_one' + LANGUAGE C STRICT; + +-- note overloading of SQL function name "add_one" +CREATE FUNCTION add_one(double precision) RETURNS double precision + AS '<replaceable>DIRECTORY</replaceable>/funcs', 'add_one_float8' + LANGUAGE C STRICT; + +CREATE FUNCTION makepoint(point, point) RETURNS point + AS '<replaceable>DIRECTORY</replaceable>/funcs', 'makepoint' + LANGUAGE C STRICT; + +CREATE FUNCTION copytext(text) RETURNS text + AS '<replaceable>DIRECTORY</replaceable>/funcs', 'copytext' + LANGUAGE C STRICT; + +CREATE FUNCTION concat_text(text, text) RETURNS text + AS '<replaceable>DIRECTORY</replaceable>/funcs', 'concat_text' + LANGUAGE C STRICT; +</programlisting> + <para> - The <command>CREATE FUNCTION</command> commands are the same as - for the version-0 equivalents. + Here, <replaceable>DIRECTORY</replaceable> stands for the + directory of the shared library file (for instance the + <productname>PostgreSQL</productname> tutorial directory, which + contains the code for the examples used in this section). + (Better style would be to use just <literal>'funcs'</> in the + <literal>AS</> clause, after having added + <replaceable>DIRECTORY</replaceable> to the search path. In any + case, we can omit the system-specific extension for a shared + library, commonly <literal>.so</literal>.) </para> <para> - At first glance, the version-1 coding conventions might appear to - be just pointless obscurantism. They do, however, offer a number - of improvements, because the macros can hide unnecessary detail. - An example is that in coding <function>add_one_float8</>, we no longer need to - be aware that <type>float8</type> is a pass-by-reference type. Another - example is that the <literal>GETARG</> macros for variable-length types allow - for more efficient fetching of <quote>toasted</quote> (compressed or + Notice that we have specified the functions as <quote>strict</quote>, + meaning that + the system should automatically assume a null result if any input + value is null. By doing this, we avoid having to check for null inputs + in the function code. Without this, we'd have to check for null values + explicitly, using PG_ARGISNULL(). + </para> + + <para> + At first glance, the version-1 coding conventions might appear to be just + pointless obscurantism, over using plain <literal>C</> calling + conventions. They do however allow to deal with <literal>NULL</>able + arguments/return values, and <quote>toasted</quote> (compressed or out-of-line) values. </para> <para> - One big improvement in version-1 functions is better handling of null - inputs and results. The macro <function>PG_ARGISNULL(<replaceable>n</>)</function> + The macro <function>PG_ARGISNULL(<replaceable>n</>)</function> allows a function to test whether each input is null. (Of course, doing this is only necessary in functions not declared <quote>strict</>.) As with the @@ -2438,7 +2353,7 @@ concat_text(PG_FUNCTION_ARGS) </para> <para> - Other options provided in the new-style interface are two + Other options provided by the version-1 interface are two variants of the <function>PG_GETARG_<replaceable>xxx</replaceable>()</function> macros. The first of these, @@ -2470,9 +2385,7 @@ concat_text(PG_FUNCTION_ARGS) to return set results (<xref linkend="xfunc-c-return-set">) and implement trigger functions (<xref linkend="triggers">) and procedural-language call handlers (<xref - linkend="plhandler">). Version-1 code is also more - portable than version-0, because it does not break restrictions - on function call protocol in the C standard. For more details + linkend="plhandler">). For more details see <filename>src/backend/utils/fmgr/README</filename> in the source distribution. </para> @@ -2607,7 +2520,7 @@ SELECT name, c_overpaid(emp, 1500) AS overpaid WHERE name = 'Bill' OR name = 'Sam'; </programlisting> - Using call conventions version 0, we can define + Using the version-1 calling conventions, we can define <function>c_overpaid</> as: <programlisting><![CDATA[ @@ -2618,31 +2531,6 @@ SELECT name, c_overpaid(emp, 1500) AS overpaid PG_MODULE_MAGIC; #endif -bool -c_overpaid(HeapTupleHeader t, /* the current row of emp */ - int32 limit) -{ - bool isnull; - int32 salary; - - salary = DatumGetInt32(GetAttributeByName(t, "salary", &isnull)); - if (isnull) - return false; - return salary > limit; -} -]]> -</programlisting> - - In version-1 coding, the above would look like this: - -<programlisting><![CDATA[ -#include "postgres.h" -#include "executor/executor.h" /* for GetAttributeByName() */ - -#ifdef PG_MODULE_MAGIC -PG_MODULE_MAGIC; -#endif - PG_FUNCTION_INFO_V1(c_overpaid); Datum @@ -2824,7 +2712,7 @@ HeapTuple heap_form_tuple(TupleDesc tupdesc, Datum *values, bool *isnull) HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values) </programlisting> to build a <structname>HeapTuple</> given user data - in C string form. <literal>values</literal> is an array of C strings, + in C string form. <parameter>values</parameter> is an array of C strings, one for each attribute of the return row. Each C string should be in the form expected by the input function of the attribute data type. In order to return a null value for one of the attributes, @@ -2872,7 +2760,7 @@ HeapTupleGetDatum(HeapTuple tuple) is used to hold a pointer to <structname>FuncCallContext</> across calls. <programlisting> -typedef struct +typedef struct FuncCallContext { /* * Number of times we've been called before @@ -2880,7 +2768,7 @@ typedef struct * call_cntr is initialized to 0 for you by SRF_FIRSTCALL_INIT(), and * incremented for you every time SRF_RETURN_NEXT() is called. */ - uint32 call_cntr; + uint64 call_cntr; /* * OPTIONAL maximum number of calls @@ -2889,7 +2777,7 @@ typedef struct * If not set, you must provide alternative means to know when the * function is done. */ - uint32 max_calls; + uint64 max_calls; /* * OPTIONAL pointer to result slot diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml index f0b711e2ce..333a36c456 100644 --- a/doc/src/sgml/xindex.sgml +++ b/doc/src/sgml/xindex.sgml @@ -288,7 +288,7 @@ have a fixed set of strategies either. Instead the support routines of each operator class interpret the strategy numbers according to the operator class's definition. As an example, the strategy numbers used by - the built-in operator classes for arrays are shown in + the built-in operator class for arrays are shown in <xref linkend="xindex-gin-array-strat-table">. </para> diff --git a/doc/src/sgml/xml2.sgml b/doc/src/sgml/xml2.sgml index a40172c36d..9bbc9e75d7 100644 --- a/doc/src/sgml/xml2.sgml +++ b/doc/src/sgml/xml2.sgml @@ -53,7 +53,7 @@ <row> <entry> <function> - xml_is_well_formed(document) + xml_valid(document) </function> </entry> <entry> @@ -62,10 +62,10 @@ <entry> <para> This parses the document text in its parameter and returns true if the - document is well-formed XML. (Note: before PostgreSQL 8.2, this - function was called <function>xml_valid()</>. That is the wrong name - since validity and well-formedness have different meanings in XML. - The old name is still available, but is deprecated.) + document is well-formed XML. (Note: this is an alias for the standard + PostgreSQL function <function>xml_is_well_formed()</>. The + name <function>xml_valid()</> is technically incorrect since validity + and well-formedness have different meanings in XML.) </para> </entry> </row> diff --git a/doc/src/sgml/xplang.sgml b/doc/src/sgml/xplang.sgml index 9fa97d4c70..4460c8f361 100644 --- a/doc/src/sgml/xplang.sgml +++ b/doc/src/sgml/xplang.sgml @@ -56,14 +56,7 @@ For the languages supplied with the standard distribution, it is only necessary to execute <command>CREATE EXTENSION</> <replaceable>language_name</> to install the language into the - current database. Alternatively, the program <xref - linkend="app-createlang"> can be used to do this from the shell - command line. For example, to install the language - <application>PL/Perl</application> into the database - <literal>template1</>, use: -<programlisting> -createlang plperl template1 -</programlisting> + current database. The manual procedure described below is only recommended for installing languages that have not been packaged as extensions. </para> |