database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-06-20 15:22:23 +03:00
Code Activity

Convert documentation to DocBook XML

Browse Source 
Since some preparation work had already been done, the only source
changes left were changing empty-element tags like <xref linkend="foo">
to <xref linkend="foo"/>, and changing the DOCTYPE.

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

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

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

Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
This commit is contained in:
Peter Eisentraut
2017-11-23 09:39:47 -05:00
parent 2f8d6369e6
commit 3c49c6facb
346 changed files with 4260 additions and 4588 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
config/docbook.m4
View File

@ -1,18 +1,18 @@
# config/docbook.m4 # config/docbook.m4
# PGAC_PROG_NSGMLS # PGAC_PATH_XMLLINT
# ---------------- # -----------------
AC_DEFUN([PGAC_PROG_NSGMLS], AC_DEFUN([PGAC_PATH_XMLLINT],
[PGAC_PATH_PROGS(NSGMLS, [onsgmls nsgmls])]) [PGAC_PATH_PROGS(XMLLINT, xmllint)])
# PGAC_CHECK_DOCBOOK(VERSION) # PGAC_CHECK_DOCBOOK(VERSION)
# --------------------------- # ---------------------------
AC_DEFUN([PGAC_CHECK_DOCBOOK], AC_DEFUN([PGAC_CHECK_DOCBOOK],
[AC_REQUIRE([PGAC_PROG_NSGMLS]) [AC_REQUIRE([PGAC_PATH_XMLLINT])
AC_CACHE_CHECK([for DocBook V$1], [pgac_cv_check_docbook], AC_CACHE_CHECK([for DocBook XML V$1], [pgac_cv_check_docbook],
[cat >conftest.sgml <<EOF [cat >conftest.xml <<EOF
<!doctype book PUBLIC "-//OASIS//DTD DocBook V$1//EN"> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V$1//EN" "http://www.oasis-open.org/docbook/xml/$1/docbookx.dtd">
<book> <book>
<title>test</title> <title>test</title>
<chapter> <chapter>
@ -27,13 +27,13 @@ EOF
pgac_cv_check_docbook=no pgac_cv_check_docbook=no
if test -n "$NSGMLS"; then if test -n "$XMLLINT"; then
$NSGMLS -s conftest.sgml 1>&AS_MESSAGE_LOG_FD 2>&1 $XMLLINT --noout --valid conftest.xml 1>&AS_MESSAGE_LOG_FD 2>&1
if test $? -eq 0; then if test $? -eq 0; then
pgac_cv_check_docbook=yes pgac_cv_check_docbook=yes
fi fi
fi fi
rm -f conftest.sgml]) rm -f conftest.xml])
have_docbook=$pgac_cv_check_docbook have_docbook=$pgac_cv_check_docbook
AC_SUBST([have_docbook]) AC_SUBST([have_docbook])

158
configure vendored
View File

@ -630,12 +630,10 @@ vpath_build
PG_VERSION_NUM PG_VERSION_NUM
PROVE PROVE
FOP FOP
OSX
XSLTPROC XSLTPROC
XMLLINT
DBTOEPUB DBTOEPUB
have_docbook have_docbook
NSGMLS XMLLINT
TCL_SHLIB_LD_LIBS TCL_SHLIB_LD_LIBS
TCL_SHARED_BUILD TCL_SHARED_BUILD
TCL_LIB_SPEC TCL_LIB_SPEC
@ -16132,19 +16130,19 @@ fi
# #
# Check for DocBook and tools # Check for DocBook and tools
# #
if test -z "$NSGMLS"; then if test -z "$XMLLINT"; then
for ac_prog in onsgmls nsgmls for ac_prog in xmllint
do do
# Extract the first word of "$ac_prog", so it can be a program name with args. # Extract the first word of "$ac_prog", so it can be a program name with args.
set dummy $ac_prog; ac_word=$2 set dummy $ac_prog; ac_word=$2
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 { $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
$as_echo_n "checking for $ac_word... " >&6; } $as_echo_n "checking for $ac_word... " >&6; }
if ${ac_cv_path_NSGMLS+:} false; then : if ${ac_cv_path_XMLLINT+:} false; then :
$as_echo_n "(cached) " >&6 $as_echo_n "(cached) " >&6
else else
case $NSGMLS in case $XMLLINT in
[\\/]* | ?:[\\/]*) [\\/]* | ?:[\\/]*)
ac_cv_path_NSGMLS="$NSGMLS" # Let the user override the test with a path. ac_cv_path_XMLLINT="$XMLLINT" # Let the user override the test with a path.
;; ;;
*) *)
as_save_IFS=$IFS; IFS=$PATH_SEPARATOR as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
@ -16154,7 +16152,7 @@ do
test -z "$as_dir" && as_dir=. test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do for ac_exec_ext in '' $ac_executable_extensions; do
if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
ac_cv_path_NSGMLS="$as_dir/$ac_word$ac_exec_ext" ac_cv_path_XMLLINT="$as_dir/$ac_word$ac_exec_ext"
$as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5 $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2 break 2
fi fi
@ -16165,35 +16163,35 @@ IFS=$as_save_IFS
;; ;;
esac esac
fi fi
NSGMLS=$ac_cv_path_NSGMLS XMLLINT=$ac_cv_path_XMLLINT
if test -n "$NSGMLS"; then if test -n "$XMLLINT"; then
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: $NSGMLS" >&5 { $as_echo "$as_me:${as_lineno-$LINENO}: result: $XMLLINT" >&5
$as_echo "$NSGMLS" >&6; } $as_echo "$XMLLINT" >&6; }
else else
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
$as_echo "no" >&6; } $as_echo "no" >&6; }
fi fi
test -n "$NSGMLS" && break test -n "$XMLLINT" && break
done done
else else
# Report the value of NSGMLS in configure's output in all cases. # Report the value of XMLLINT in configure's output in all cases.
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for NSGMLS" >&5 { $as_echo "$as_me:${as_lineno-$LINENO}: checking for XMLLINT" >&5
$as_echo_n "checking for NSGMLS... " >&6; } $as_echo_n "checking for XMLLINT... " >&6; }
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: $NSGMLS" >&5 { $as_echo "$as_me:${as_lineno-$LINENO}: result: $XMLLINT" >&5
$as_echo "$NSGMLS" >&6; } $as_echo "$XMLLINT" >&6; }
fi fi
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for DocBook V4.2" >&5 { $as_echo "$as_me:${as_lineno-$LINENO}: checking for DocBook XML V4.2" >&5
$as_echo_n "checking for DocBook V4.2... " >&6; } $as_echo_n "checking for DocBook XML V4.2... " >&6; }
if ${pgac_cv_check_docbook+:} false; then : if ${pgac_cv_check_docbook+:} false; then :
$as_echo_n "(cached) " >&6 $as_echo_n "(cached) " >&6
else else
cat >conftest.sgml <<EOF cat >conftest.xml <<EOF
<!doctype book PUBLIC "-//OASIS//DTD DocBook V4.2//EN"> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<book> <book>
<title>test</title> <title>test</title>
<chapter> <chapter>
@ -16208,13 +16206,13 @@ EOF
pgac_cv_check_docbook=no pgac_cv_check_docbook=no
if test -n "$NSGMLS"; then if test -n "$XMLLINT"; then
$NSGMLS -s conftest.sgml 1>&5 2>&1 $XMLLINT --noout --valid conftest.xml 1>&5 2>&1
if test $? -eq 0; then if test $? -eq 0; then
pgac_cv_check_docbook=yes pgac_cv_check_docbook=yes
fi fi
fi fi
rm -f conftest.sgml rm -f conftest.xml
fi fi
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: $pgac_cv_check_docbook" >&5 { $as_echo "$as_me:${as_lineno-$LINENO}: result: $pgac_cv_check_docbook" >&5
$as_echo "$pgac_cv_check_docbook" >&6; } $as_echo "$pgac_cv_check_docbook" >&6; }
@ -16276,60 +16274,6 @@ $as_echo_n "checking for DBTOEPUB... " >&6; }
$as_echo "$DBTOEPUB" >&6; } $as_echo "$DBTOEPUB" >&6; }
fi fi
if test -z "$XMLLINT"; then
for ac_prog in xmllint
do
# Extract the first word of "$ac_prog", so it can be a program name with args.
set dummy $ac_prog; ac_word=$2
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
$as_echo_n "checking for $ac_word... " >&6; }
if ${ac_cv_path_XMLLINT+:} false; then :
$as_echo_n "(cached) " >&6
else
case $XMLLINT in
[\\/]* | ?:[\\/]*)
ac_cv_path_XMLLINT="$XMLLINT" # Let the user override the test with a path.
;;
*)
as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
for as_dir in $PATH
do
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
ac_cv_path_XMLLINT="$as_dir/$ac_word$ac_exec_ext"
$as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
fi
done
done
IFS=$as_save_IFS
;;
esac
fi
XMLLINT=$ac_cv_path_XMLLINT
if test -n "$XMLLINT"; then
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: $XMLLINT" >&5
$as_echo "$XMLLINT" >&6; }
else
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
$as_echo "no" >&6; }
fi
test -n "$XMLLINT" && break
done
else
# Report the value of XMLLINT in configure's output in all cases.
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for XMLLINT" >&5
$as_echo_n "checking for XMLLINT... " >&6; }
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: $XMLLINT" >&5
$as_echo "$XMLLINT" >&6; }
fi
if test -z "$XSLTPROC"; then if test -z "$XSLTPROC"; then
for ac_prog in xsltproc for ac_prog in xsltproc
do do
@ -16384,60 +16328,6 @@ $as_echo_n "checking for XSLTPROC... " >&6; }
$as_echo "$XSLTPROC" >&6; } $as_echo "$XSLTPROC" >&6; }
fi fi
if test -z "$OSX"; then
for ac_prog in osx sgml2xml sx
do
# Extract the first word of "$ac_prog", so it can be a program name with args.
set dummy $ac_prog; ac_word=$2
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
$as_echo_n "checking for $ac_word... " >&6; }
if ${ac_cv_path_OSX+:} false; then :
$as_echo_n "(cached) " >&6
else
case $OSX in
[\\/]* | ?:[\\/]*)
ac_cv_path_OSX="$OSX" # Let the user override the test with a path.
;;
*)
as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
for as_dir in $PATH
do
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
ac_cv_path_OSX="$as_dir/$ac_word$ac_exec_ext"
$as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
fi
done
done
IFS=$as_save_IFS
;;
esac
fi
OSX=$ac_cv_path_OSX
if test -n "$OSX"; then
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: $OSX" >&5
$as_echo "$OSX" >&6; }
else
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
$as_echo "no" >&6; }
fi
test -n "$OSX" && break
done
else
# Report the value of OSX in configure's output in all cases.
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for OSX" >&5
$as_echo_n "checking for OSX... " >&6; }
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: $OSX" >&5
$as_echo "$OSX" >&6; }
fi
if test -z "$FOP"; then if test -z "$FOP"; then
for ac_prog in fop for ac_prog in fop
do do

4
configure.in
View File

@ -2091,12 +2091,10 @@ fi
# #
# Check for DocBook and tools # Check for DocBook and tools
# #
PGAC_PROG_NSGMLS PGAC_PATH_XMLLINT
PGAC_CHECK_DOCBOOK(4.2) PGAC_CHECK_DOCBOOK(4.2)
PGAC_PATH_PROGS(DBTOEPUB, dbtoepub) PGAC_PATH_PROGS(DBTOEPUB, dbtoepub)
PGAC_PATH_PROGS(XMLLINT, xmllint)
PGAC_PATH_PROGS(XSLTPROC, xsltproc) PGAC_PATH_PROGS(XSLTPROC, xsltproc)
PGAC_PATH_PROGS(OSX, [osx sgml2xml sx])
PGAC_PATH_PROGS(FOP, fop) PGAC_PATH_PROGS(FOP, fop)
# #

93
doc/src/sgml/Makefile
View File

@ -37,15 +37,7 @@ ifndef FOP
FOP = $(missing) fop FOP = $(missing) fop
endif endif
SGMLINCLUDE = -D . -D $(srcdir) XMLINCLUDE = --path .
ifndef NSGMLS
NSGMLS = $(missing) nsgmls
endif
ifndef OSX
OSX = $(missing) osx
endif
ifndef XMLLINT ifndef XMLLINT
XMLLINT = $(missing) xmllint XMLLINT = $(missing) xmllint
@ -63,19 +55,6 @@ GENERATED_SGML = version.sgml \
ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML) ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML)
# Enable some extra warnings
# -wfully-tagged needed to throw a warning on missing tags
# for older tool chains, 2007-08-31
# -wnet catches XML-style empty-element tags like <xref linkend="abc"/>.
override SPFLAGS += -wall -wno-unused-param -wfully-tagged -wnet
# Additional warnings for XML compatibility. The conditional is meant
# to detect whether we are using OpenSP rather than the ancient
# original SP.
override SPFLAGS += -wempty
ifneq (,$(filter o%,$(notdir $(OSX))))
override SPFLAGS += -wdata-delim -winstance-ignore-ms -winstance-include-ms -winstance-param-entity
endif
## ##
## Man pages ## Man pages
@ -83,9 +62,9 @@ endif
man distprep-man: man-stamp man distprep-man: man-stamp
man-stamp: stylesheet-man.xsl postgres.xml man-stamp: stylesheet-man.xsl postgres.sgml $(ALLSGML)
$(XMLLINT) --noout --valid postgres.xml $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
$(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_MAN_FLAGS) $^ $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_MAN_FLAGS) $(wordlist 1,2,$^)
touch $@ touch $@
@ -136,27 +115,8 @@ INSTALL.html: %.html : stylesheet-text.xsl %.xml
$(XMLLINT) --noout --valid $*.xml $(XMLLINT) --noout --valid $*.xml
$(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ >$@ $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ >$@
INSTALL.xml: standalone-profile.xsl standalone-install.xml postgres.xml INSTALL.xml: standalone-profile.xsl standalone-install.xml postgres.sgml $(ALLSGML)
$(XSLTPROC) $(XSLTPROCFLAGS) --xinclude $(wordlist 1,2,$^) >$@ $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --xinclude $(wordlist 1,2,$^) >$@
##
## 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 $(ALLSGML)
$(OSX) $(SPFLAGS) $(SGMLINCLUDE) -x lower $< >$@.tmp
$(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;' \
<$@.tmp > $@
rm $@.tmp
endef
## ##
@ -169,20 +129,20 @@ endif
html: html-stamp html: html-stamp
html-stamp: stylesheet.xsl postgres.xml html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML)
$(XMLLINT) --noout --valid postgres.xml $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
$(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $(wordlist 1,2,$^)
cp $(srcdir)/stylesheet.css html/ cp $(srcdir)/stylesheet.css html/
touch $@ touch $@
htmlhelp: stylesheet-hh.xsl postgres.xml htmlhelp: stylesheet-hh.xsl postgres.sgml $(ALLSGML)
$(XMLLINT) --noout --valid postgres.xml $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
$(XSLTPROC) $(XSLTPROCFLAGS) $^ $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(wordlist 1,2,$^)
# single-page HTML # single-page HTML
postgres.html: stylesheet-html-nochunk.xsl postgres.xml postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML)
$(XMLLINT) --noout --valid postgres.xml $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
$(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $^ $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $(wordlist 1,2,$^)
# single-page text # single-page text
postgres.txt: postgres.html postgres.txt: postgres.html
@ -196,13 +156,13 @@ postgres.txt: postgres.html
postgres.pdf: postgres.pdf:
$(error Invalid target; use postgres-A4.pdf or postgres-US.pdf as targets) $(error Invalid target; use postgres-A4.pdf or postgres-US.pdf as targets)
%-A4.fo: stylesheet-fo.xsl %.xml %-A4.fo: stylesheet-fo.xsl %.sgml $(ALLSGML)
$(XMLLINT) --noout --valid $*.xml $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
$(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type A4 -o $@ $^ $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type A4 -o $@ $(wordlist 1,2,$^)
%-US.fo: stylesheet-fo.xsl %.xml %-US.fo: stylesheet-fo.xsl %.sgml $(ALLSGML)
$(XMLLINT) --noout --valid $*.xml $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
$(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $^ $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^)
%.pdf: %.fo %.pdf: %.fo
$(FOP) -fo $< -pdf $@ $(FOP) -fo $< -pdf $@
@ -213,7 +173,7 @@ postgres.pdf:
## ##
epub: postgres.epub epub: postgres.epub
postgres.epub: postgres.xml postgres.epub: postgres.sgml $(ALLSGML)
$(XMLLINT) --noout --valid $< $(XMLLINT) --noout --valid $<
$(DBTOEPUB) $< $(DBTOEPUB) $<
@ -226,7 +186,8 @@ DB2X_TEXIXML = db2x_texixml
DB2X_XSLTPROC = db2x_xsltproc DB2X_XSLTPROC = db2x_xsltproc
MAKEINFO = makeinfo MAKEINFO = makeinfo
%.texixml: %.xml %.texixml: %.sgml $(ALLSGML)
$(XMLLINT) --noout --valid $<
$(DB2X_XSLTPROC) -s texi -g output-file=$(basename $@) $< -o $@ $(DB2X_XSLTPROC) -s texi -g output-file=$(basename $@) $< -o $@
%.texi: %.texixml %.texi: %.texixml
@ -242,7 +203,7 @@ MAKEINFO = makeinfo
# Quick syntax check without style processing # Quick syntax check without style processing
check: postgres.sgml $(ALLSGML) check-tabs check: postgres.sgml $(ALLSGML) check-tabs
$(NSGMLS) $(SPFLAGS) $(SGMLINCLUDE) -s $< $(XMLLINT) $(XMLINCLUDE) --noout --valid $<
## ##
@ -312,7 +273,7 @@ check-tabs:
# This allows removing some files from the distribution tarballs while # This allows removing some files from the distribution tarballs while
# keeping the dependencies satisfied. # keeping the dependencies satisfied.
.SECONDARY: postgres.xml $(GENERATED_SGML) .SECONDARY: $(GENERATED_SGML)
.SECONDARY: INSTALL.html INSTALL.xml .SECONDARY: INSTALL.html INSTALL.xml
.SECONDARY: postgres-A4.fo postgres-US.fo .SECONDARY: postgres-A4.fo postgres-US.fo
@ -326,8 +287,6 @@ clean:
rm -f *.fo *.pdf rm -f *.fo *.pdf
# generated SGML files # generated SGML files
rm -f $(GENERATED_SGML) rm -f $(GENERATED_SGML)
# SGML->XML conversion
rm -f postgres.xml *.tmp
# HTML Help # HTML Help
rm -f htmlhelp.hhp toc.hhc index.hhk rm -f htmlhelp.hhp toc.hhc index.hhk
# EPUB # EPUB

14
doc/src/sgml/adminpack.sgml
View File

@ -16,9 +16,9 @@
</para> </para>
<para> <para>
The functions shown in <xref linkend="functions-adminpack-table"> provide The functions shown in <xref linkend="functions-adminpack-table"/> provide
write access to files on the machine hosting the server. (See also the write access to files on the machine hosting the server. (See also the
functions in <xref linkend="functions-admin-genfile-table">, which functions in <xref linkend="functions-admin-genfile-table"/>, which
provide read-only access.) provide read-only access.)
Only files within the database cluster directory can be accessed, but Only files within the database cluster directory can be accessed, but
either a relative or absolute path is allowable. either a relative or absolute path is allowable.
@ -107,18 +107,18 @@
</indexterm> </indexterm>
<para> <para>
<function>pg_logdir_ls</function> returns the start timestamps and path <function>pg_logdir_ls</function> returns the start timestamps and path
names of all the log files in the <xref linkend="guc-log-directory"> names of all the log files in the <xref linkend="guc-log-directory"/>
directory. The <xref linkend="guc-log-filename"> parameter must have its directory. The <xref linkend="guc-log-filename"/> parameter must have its
default setting (<literal>postgresql-%Y-%m-%d_%H%M%S.log</literal>) to use this default setting (<literal>postgresql-%Y-%m-%d_%H%M%S.log</literal>) to use this
function. function.
</para> </para>
<para> <para>
The functions shown The functions shown
in <xref linkend="functions-adminpack-deprecated-table"> are deprecated in <xref linkend="functions-adminpack-deprecated-table"/> are deprecated
and should not be used in new applications; instead use those shown and should not be used in new applications; instead use those shown
in <xref linkend="functions-admin-signal-table"> in <xref linkend="functions-admin-signal-table"/>
and <xref linkend="functions-admin-genfile-table">. These functions are and <xref linkend="functions-admin-genfile-table"/>. These functions are
provided in <filename>adminpack</filename> only for compatibility with old provided in <filename>adminpack</filename> only for compatibility with old
versions of <application>pgAdmin</application>. versions of <application>pgAdmin</application>.
</para> </para>

22
doc/src/sgml/advanced.sgml
View File

@ -18,12 +18,12 @@
<para> <para>
This chapter will on occasion refer to examples found in <xref This chapter will on occasion refer to examples found in <xref
linkend="tutorial-sql"> to change or improve them, so it will be linkend="tutorial-sql"/> to change or improve them, so it will be
useful to have read that chapter. Some examples from useful to have read that chapter. Some examples from
this chapter can also be found in this chapter can also be found in
<filename>advanced.sql</filename> in the tutorial directory. This <filename>advanced.sql</filename> in the tutorial directory. This
file also contains some sample data to load, which is not file also contains some sample data to load, which is not
repeated here. (Refer to <xref linkend="tutorial-sql-intro"> for repeated here. (Refer to <xref linkend="tutorial-sql-intro"/> for
how to use the file.) how to use the file.)
</para> </para>
</sect1> </sect1>
@ -37,7 +37,7 @@
</indexterm> </indexterm>
<para> <para>
Refer back to the queries in <xref linkend="tutorial-join">. Refer back to the queries in <xref linkend="tutorial-join"/>.
Suppose the combined listing of weather records and city location Suppose the combined listing of weather records and city location
is of particular interest to your application, but you do not want is of particular interest to your application, but you do not want
to type the query each time you need it. You can create a to type the query each time you need it. You can create a
@ -82,7 +82,7 @@ SELECT * FROM myview;
<para> <para>
Recall the <classname>weather</classname> and Recall the <classname>weather</classname> and
<classname>cities</classname> tables from <xref <classname>cities</classname> tables from <xref
linkend="tutorial-sql">. Consider the following problem: You linkend="tutorial-sql"/>. Consider the following problem: You
want to make sure that no one can insert rows in the want to make sure that no one can insert rows in the
<classname>weather</classname> table that do not have a matching <classname>weather</classname> table that do not have a matching
entry in the <classname>cities</classname> table. This is called entry in the <classname>cities</classname> table. This is called
@ -129,7 +129,7 @@ DETAIL: Key (city)=(Berkeley) is not present in table "cities".
<para> <para>
The behavior of foreign keys can be finely tuned to your The behavior of foreign keys can be finely tuned to your
application. We will not go beyond this simple example in this application. We will not go beyond this simple example in this
tutorial, but just refer you to <xref linkend="ddl"> tutorial, but just refer you to <xref linkend="ddl"/>
for more information. Making correct use of for more information. Making correct use of
foreign keys will definitely improve the quality of your database foreign keys will definitely improve the quality of your database
applications, so you are strongly encouraged to learn about them. applications, so you are strongly encouraged to learn about them.
@ -447,7 +447,7 @@ FROM empsalary;
<para> <para>
There are options to define the window frame in other ways, but There are options to define the window frame in other ways, but
this tutorial does not cover them. See this tutorial does not cover them. See
<xref linkend="syntax-window-functions"> for details. <xref linkend="syntax-window-functions"/> for details.
</para> </para>
</footnote> </footnote>
Here is an example using <function>sum</function>: Here is an example using <function>sum</function>:
@ -554,10 +554,10 @@ SELECT sum(salary) OVER w, avg(salary) OVER w
<para> <para>
More details about window functions can be found in More details about window functions can be found in
<xref linkend="syntax-window-functions">, <xref linkend="syntax-window-functions"/>,
<xref linkend="functions-window">, <xref linkend="functions-window"/>,
<xref linkend="queries-window">, and the <xref linkend="queries-window"/>, and the
<xref linkend="sql-select"> reference page. <xref linkend="sql-select"/> reference page.
</para> </para>
</sect1> </sect1>
@ -692,7 +692,7 @@ SELECT name, altitude
<para> <para>
Although inheritance is frequently useful, it has not been integrated Although inheritance is frequently useful, it has not been integrated
with unique constraints or foreign keys, which limits its usefulness. with unique constraints or foreign keys, which limits its usefulness.
See <xref linkend="ddl-inherit"> for more detail. See <xref linkend="ddl-inherit"/> for more detail.
</para> </para>
</note> </note>
</sect1> </sect1>

8
doc/src/sgml/amcheck.sgml
View File

@ -31,7 +31,7 @@
index scans themselves, which may be user-defined operator class index scans themselves, which may be user-defined operator class
code. For example, B-Tree index verification relies on comparisons code. For example, B-Tree index verification relies on comparisons
made with one or more B-Tree support function 1 routines. See <xref made with one or more B-Tree support function 1 routines. See <xref
linkend="xindex-support"> for details of operator class support linkend="xindex-support"/> for details of operator class support
functions. functions.
</para> </para>
<para> <para>
@ -192,7 +192,7 @@ ORDER BY c.relpages DESC LIMIT 10;
index that is ordered using an affected collation, simply because index that is ordered using an affected collation, simply because
<emphasis>indexed</emphasis> values might happen to have the same <emphasis>indexed</emphasis> values might happen to have the same
absolute ordering regardless of the behavioral inconsistency. See absolute ordering regardless of the behavioral inconsistency. See
<xref linkend="locale"> and <xref linkend="collation"> for <xref linkend="locale"/> and <xref linkend="collation"/> for
further details about how <productname>PostgreSQL</productname> uses further details about how <productname>PostgreSQL</productname> uses
operating system locales and collations. operating system locales and collations.
</para> </para>
@ -210,7 +210,7 @@ ORDER BY c.relpages DESC LIMIT 10;
logical inconsistency to be introduced. One obvious testing logical inconsistency to be introduced. One obvious testing
strategy is to call <filename>amcheck</filename> functions continuously strategy is to call <filename>amcheck</filename> functions continuously
when running the standard regression tests. See <xref when running the standard regression tests. See <xref
linkend="regress-run"> for details on running the tests. linkend="regress-run"/> for details on running the tests.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -263,7 +263,7 @@ ORDER BY c.relpages DESC LIMIT 10;
There is no general method of repairing problems that There is no general method of repairing problems that
<filename>amcheck</filename> detects. An explanation for the root cause of <filename>amcheck</filename> detects. An explanation for the root cause of
an invariant violation should be sought. <xref an invariant violation should be sought. <xref
linkend="pageinspect"> may play a useful role in diagnosing linkend="pageinspect"/> may play a useful role in diagnosing
corruption that <filename>amcheck</filename> detects. A <command>REINDEX</command> corruption that <filename>amcheck</filename> detects. A <command>REINDEX</command>
may not be effective in repairing corruption. may not be effective in repairing corruption.
</para> </para>

14
doc/src/sgml/arch-dev.sgml
View File

@ -7,7 +7,7 @@
<title>Author</title> <title>Author</title>
<para> <para>
This chapter originated as part of This chapter originated as part of
<xref linkend="sim98">, Stefan Simkovics' <xref linkend="sim98"/>, Stefan Simkovics'
Master's Thesis prepared at Vienna University of Technology under the direction Master's Thesis prepared at Vienna University of Technology under the direction
of O.Univ.Prof.Dr. Georg Gottlob and Univ.Ass. Mag. Katrin Seyr. of O.Univ.Prof.Dr. Georg Gottlob and Univ.Ass. Mag. Katrin Seyr.
</para> </para>
@ -136,7 +136,7 @@
<para> <para>
The client process can be any program that understands the The client process can be any program that understands the
<productname>PostgreSQL</productname> protocol described in <productname>PostgreSQL</productname> protocol described in
<xref linkend="protocol">. Many clients are based on the <xref linkend="protocol"/>. Many clients are based on the
C-language library <application>libpq</application>, but several independent C-language library <application>libpq</application>, but several independent
implementations of the protocol exist, such as the Java implementations of the protocol exist, such as the Java
<application>JDBC</application> driver. <application>JDBC</application> driver.
@ -317,7 +317,7 @@
<para> <para>
The query rewriter is discussed in some detail in The query rewriter is discussed in some detail in
<xref linkend="rules">, so there is no need to cover it here. <xref linkend="rules"/>, so there is no need to cover it here.
We will only point out that both the input and the output of the We will only point out that both the input and the output of the
rewriter are query trees, that is, there is no change in the rewriter are query trees, that is, there is no change in the
representation or level of semantic detail in the trees. Rewriting representation or level of semantic detail in the trees. Rewriting
@ -347,8 +347,8 @@
involving large numbers of join operations. In order to determine involving large numbers of join operations. In order to determine
a reasonable (not necessarily optimal) query plan in a reasonable amount a reasonable (not necessarily optimal) query plan in a reasonable amount
of time, <productname>PostgreSQL</productname> uses a <firstterm>Genetic of time, <productname>PostgreSQL</productname> uses a <firstterm>Genetic
Query Optimizer</firstterm> (see <xref linkend="geqo">) when the number of joins Query Optimizer</firstterm> (see <xref linkend="geqo"/>) when the number of joins
exceeds a threshold (see <xref linkend="guc-geqo-threshold">). exceeds a threshold (see <xref linkend="guc-geqo-threshold"/>).
</para> </para>
</note> </note>
@ -438,7 +438,7 @@
</para> </para>
<para> <para>
If the query uses fewer than <xref linkend="guc-geqo-threshold"> If the query uses fewer than <xref linkend="guc-geqo-threshold"/>
relations, a near-exhaustive search is conducted to find the best relations, a near-exhaustive search is conducted to find the best
join sequence. The planner preferentially considers joins between any join sequence. The planner preferentially considers joins between any
two relations for which there exist a corresponding join clause in the two relations for which there exist a corresponding join clause in the
@ -454,7 +454,7 @@
<para> <para>
When <varname>geqo_threshold</varname> is exceeded, the join When <varname>geqo_threshold</varname> is exceeded, the join
sequences considered are determined by heuristics, as described sequences considered are determined by heuristics, as described
in <xref linkend="geqo">. Otherwise the process is the same. in <xref linkend="geqo"/>. Otherwise the process is the same.
</para> </para>
<para> <para>

18
doc/src/sgml/array.sgml
View File

@ -128,7 +128,7 @@ CREATE TABLE tictactoe (
<para> <para>
(These kinds of array constants are actually only a special case of (These kinds of array constants are actually only a special case of
the generic type constants discussed in <xref the generic type constants discussed in <xref
linkend="sql-syntax-constants-generic">. The constant is initially linkend="sql-syntax-constants-generic"/>. The constant is initially
treated as a string and passed to the array input conversion treated as a string and passed to the array input conversion
routine. An explicit type specification might be necessary.) routine. An explicit type specification might be necessary.)
</para> </para>
@ -192,7 +192,7 @@ INSERT INTO sal_emp
expressions; for instance, string literals are single quoted, instead of expressions; for instance, string literals are single quoted, instead of
double quoted as they would be in an array literal. The <literal>ARRAY</literal> double quoted as they would be in an array literal. The <literal>ARRAY</literal>
constructor syntax is discussed in more detail in constructor syntax is discussed in more detail in
<xref linkend="sql-syntax-array-constructors">. <xref linkend="sql-syntax-array-constructors"/>.
</para> </para>
</sect2> </sect2>
@ -616,7 +616,7 @@ SELECT * FROM sal_emp WHERE pay_by_quarter[1] = 10000 OR
However, this quickly becomes tedious for large arrays, and is not However, this quickly becomes tedious for large arrays, and is not
helpful if the size of the array is unknown. An alternative method is helpful if the size of the array is unknown. An alternative method is
described in <xref linkend="functions-comparisons">. The above described in <xref linkend="functions-comparisons"/>. The above
query could be replaced by: query could be replaced by:
<programlisting> <programlisting>
@ -644,7 +644,7 @@ SELECT * FROM
WHERE pay_by_quarter[s] = 10000; WHERE pay_by_quarter[s] = 10000;
</programlisting> </programlisting>
This function is described in <xref linkend="functions-srf-subscripts">. This function is described in <xref linkend="functions-srf-subscripts"/>.
</para> </para>
<para> <para>
@ -657,8 +657,8 @@ SELECT * FROM sal_emp WHERE pay_by_quarter &amp;&amp; ARRAY[10000];
</programlisting> </programlisting>
This and other array operators are further described in This and other array operators are further described in
<xref linkend="functions-array">. It can be accelerated by an appropriate <xref linkend="functions-array"/>. It can be accelerated by an appropriate
index, as described in <xref linkend="indexes-types">. index, as described in <xref linkend="indexes-types"/>.
</para> </para>
<para> <para>
@ -755,7 +755,7 @@ SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2
or backslashes disables this and allows the literal string value or backslashes disables this and allows the literal string value
<quote>NULL</quote> to be entered. Also, for backward compatibility with <quote>NULL</quote> to be entered. Also, for backward compatibility with
pre-8.2 versions of <productname>PostgreSQL</productname>, the <xref pre-8.2 versions of <productname>PostgreSQL</productname>, the <xref
linkend="guc-array-nulls"> configuration parameter can be turned linkend="guc-array-nulls"/> configuration parameter can be turned
<literal>off</literal> to suppress recognition of <literal>NULL</literal> as a NULL. <literal>off</literal> to suppress recognition of <literal>NULL</literal> as a NULL.
</para> </para>
@ -797,7 +797,7 @@ INSERT ... VALUES (E'{"\\\\","\\""}');
with a data type whose input routine also treated backslashes specially, with a data type whose input routine also treated backslashes specially,
<type>bytea</type> for example, we might need as many as eight backslashes <type>bytea</type> for example, we might need as many as eight backslashes
in the command to get one backslash into the stored array element.) in the command to get one backslash into the stored array element.)
Dollar quoting (see <xref linkend="sql-syntax-dollar-quoting">) can be Dollar quoting (see <xref linkend="sql-syntax-dollar-quoting"/>) can be
used to avoid the need to double backslashes. used to avoid the need to double backslashes.
</para> </para>
</note> </note>
@ -805,7 +805,7 @@ INSERT ... VALUES (E'{"\\\\","\\""}');
<tip> <tip>
<para> <para>
The <literal>ARRAY</literal> constructor syntax (see The <literal>ARRAY</literal> constructor syntax (see
<xref linkend="sql-syntax-array-constructors">) is often easier to work <xref linkend="sql-syntax-array-constructors"/>) is often easier to work
with than the array-literal syntax when writing array values in SQL with than the array-literal syntax when writing array values in SQL
commands. In <literal>ARRAY</literal>, individual element values are written the commands. In <literal>ARRAY</literal>, individual element values are written the
same way they would be written when not members of an array. same way they would be written when not members of an array.

2
doc/src/sgml/auth-delay.sgml
View File

@ -18,7 +18,7 @@
<para> <para>
In order to function, this module must be loaded via In order to function, this module must be loaded via
<xref linkend="guc-shared-preload-libraries"> in <filename>postgresql.conf</filename>. <xref linkend="guc-shared-preload-libraries"/> in <filename>postgresql.conf</filename>.
</para> </para>
<sect2> <sect2>

6
doc/src/sgml/auto-explain.sgml
View File

@ -10,7 +10,7 @@
<para> <para>
The <filename>auto_explain</filename> module provides a means for The <filename>auto_explain</filename> module provides a means for
logging execution plans of slow statements automatically, without logging execution plans of slow statements automatically, without
having to run <xref linkend="sql-explain"> having to run <xref linkend="sql-explain"/>
by hand. This is especially helpful for tracking down un-optimized queries by hand. This is especially helpful for tracking down un-optimized queries
in large applications. in large applications.
</para> </para>
@ -25,8 +25,8 @@ LOAD 'auto_explain';
(You must be superuser to do that.) More typical usage is to preload (You must be superuser to do that.) More typical usage is to preload
it into some or all sessions by including <literal>auto_explain</literal> in it into some or all sessions by including <literal>auto_explain</literal> in
<xref linkend="guc-session-preload-libraries"> or <xref linkend="guc-session-preload-libraries"/> or
<xref linkend="guc-shared-preload-libraries"> in <xref linkend="guc-shared-preload-libraries"/> in
<filename>postgresql.conf</filename>. Then you can track unexpectedly slow queries <filename>postgresql.conf</filename>. Then you can track unexpectedly slow queries
no matter when they happen. Of course there is a price in overhead for no matter when they happen. Of course there is a price in overhead for
that. that.

82
doc/src/sgml/backup.sgml
View File

@ -32,7 +32,7 @@
commands that, when fed back to the server, will recreate the commands that, when fed back to the server, will recreate the
database in the same state as it was at the time of the dump. database in the same state as it was at the time of the dump.
<productname>PostgreSQL</productname> provides the utility program <productname>PostgreSQL</productname> provides the utility program
<xref linkend="app-pgdump"> for this purpose. The basic usage of this <xref linkend="app-pgdump"/> for this purpose. The basic usage of this
command is: command is:
<synopsis> <synopsis>
pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable class="parameter">outfile</replaceable> pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable class="parameter">outfile</replaceable>
@ -79,7 +79,7 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
environment variable <envar>PGUSER</envar>. Remember that environment variable <envar>PGUSER</envar>. Remember that
<application>pg_dump</application> connections are subject to the normal <application>pg_dump</application> connections are subject to the normal
client authentication mechanisms (which are described in <xref client authentication mechanisms (which are described in <xref
linkend="client-authentication">). linkend="client-authentication"/>).
</para> </para>
<para> <para>
@ -120,9 +120,9 @@ psql <replaceable class="parameter">dbname</replaceable> &lt; <replaceable class
class="parameter">dbname</replaceable></literal>). <application>psql</application> class="parameter">dbname</replaceable></literal>). <application>psql</application>
supports options similar to <application>pg_dump</application> for specifying supports options similar to <application>pg_dump</application> for specifying
the database server to connect to and the user name to use. See the database server to connect to and the user name to use. See
the <xref linkend="app-psql"> reference page for more information. the <xref linkend="app-psql"/> reference page for more information.
Non-text file dumps are restored using the <xref Non-text file dumps are restored using the <xref
linkend="app-pgrestore"> utility. linkend="app-pgrestore"/> utility.
</para> </para>
<para> <para>
@ -178,13 +178,13 @@ pg_dump -h <replaceable>host1</replaceable> <replaceable>dbname</replaceable> |
<para> <para>
After restoring a backup, it is wise to run <xref After restoring a backup, it is wise to run <xref
linkend="sql-analyze"> on each linkend="sql-analyze"/> on each
database so the query optimizer has useful statistics; database so the query optimizer has useful statistics;
see <xref linkend="vacuum-for-statistics"> see <xref linkend="vacuum-for-statistics"/>
and <xref linkend="autovacuum"> for more information. and <xref linkend="autovacuum"/> for more information.
For more advice on how to load large amounts of data For more advice on how to load large amounts of data
into <productname>PostgreSQL</productname> efficiently, refer to <xref into <productname>PostgreSQL</productname> efficiently, refer to <xref
linkend="populate">. linkend="populate"/>.
</para> </para>
</sect2> </sect2>
@ -196,7 +196,7 @@ pg_dump -h <replaceable>host1</replaceable> <replaceable>dbname</replaceable> |
and it does not dump information about roles or tablespaces and it does not dump information about roles or tablespaces
(because those are cluster-wide rather than per-database). (because those are cluster-wide rather than per-database).
To support convenient dumping of the entire contents of a database To support convenient dumping of the entire contents of a database
cluster, the <xref linkend="app-pg-dumpall"> program is provided. cluster, the <xref linkend="app-pg-dumpall"/> program is provided.
<application>pg_dumpall</application> backs up each database in a given <application>pg_dumpall</application> backs up each database in a given
cluster, and also preserves cluster-wide data such as role and cluster, and also preserves cluster-wide data such as role and
tablespace definitions. The basic usage of this command is: tablespace definitions. The basic usage of this command is:
@ -308,8 +308,8 @@ pg_dump -Fc <replaceable class="parameter">dbname</replaceable> &gt; <replaceabl
pg_restore -d <replaceable class="parameter">dbname</replaceable> <replaceable class="parameter">filename</replaceable> pg_restore -d <replaceable class="parameter">dbname</replaceable> <replaceable class="parameter">filename</replaceable>
</programlisting> </programlisting>
See the <xref linkend="app-pgdump"> and <xref See the <xref linkend="app-pgdump"/> and <xref
linkend="app-pgrestore"> reference pages for details. linkend="app-pgrestore"/> reference pages for details.
</para> </para>
</formalpara> </formalpara>
@ -345,7 +345,7 @@ pg_dump -j <replaceable class="parameter">num</replaceable> -F d -f <replaceable
<para> <para>
An alternative backup strategy is to directly copy the files that An alternative backup strategy is to directly copy the files that
<productname>PostgreSQL</productname> uses to store the data in the database; <productname>PostgreSQL</productname> uses to store the data in the database;
<xref linkend="creating-cluster"> explains where these files <xref linkend="creating-cluster"/> explains where these files
are located. You can use whatever method you prefer are located. You can use whatever method you prefer
for doing file system backups; for example: for doing file system backups; for example:
@ -369,7 +369,7 @@ tar -cf backup.tar /usr/local/pgsql/data
an atomic snapshot of the state of the file system, an atomic snapshot of the state of the file system,
but also because of internal buffering within the server). but also because of internal buffering within the server).
Information about stopping the server can be found in Information about stopping the server can be found in
<xref linkend="server-shutdown">. Needless to say, you <xref linkend="server-shutdown"/>. Needless to say, you
also need to shut down the server before restoring the data. also need to shut down the server before restoring the data.
</para> </para>
</listitem> </listitem>
@ -428,10 +428,10 @@ tar -cf backup.tar /usr/local/pgsql/data
If simultaneous snapshots are not possible, one option is to shut down If simultaneous snapshots are not possible, one option is to shut down
the database server long enough to establish all the frozen snapshots. the database server long enough to establish all the frozen snapshots.
Another option is to perform a continuous archiving base backup (<xref Another option is to perform a continuous archiving base backup (<xref
linkend="backup-base-backup">) because such backups are immune to file linkend="backup-base-backup"/>) because such backups are immune to file
system changes during the backup. This requires enabling continuous system changes during the backup. This requires enabling continuous
archiving just during the backup process; restore is done using archiving just during the backup process; restore is done using
continuous archive recovery (<xref linkend="backup-pitr-recovery">). continuous archive recovery (<xref linkend="backup-pitr-recovery"/>).
</para> </para>
<para> <para>
@ -591,11 +591,11 @@ tar -cf backup.tar /usr/local/pgsql/data
</para> </para>
<para> <para>
To enable WAL archiving, set the <xref linkend="guc-wal-level"> To enable WAL archiving, set the <xref linkend="guc-wal-level"/>
configuration parameter to <literal>replica</literal> or higher, configuration parameter to <literal>replica</literal> or higher,
<xref linkend="guc-archive-mode"> to <literal>on</literal>, <xref linkend="guc-archive-mode"/> to <literal>on</literal>,
and specify the shell command to use in the <xref and specify the shell command to use in the <xref
linkend="guc-archive-command"> configuration parameter. In practice linkend="guc-archive-command"/> configuration parameter. In practice
these settings will always be placed in the these settings will always be placed in the
<filename>postgresql.conf</filename> file. <filename>postgresql.conf</filename> file.
In <varname>archive_command</varname>, In <varname>archive_command</varname>,
@ -705,7 +705,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_wal/0
than through SQL operations. than through SQL operations.
You might wish to keep the configuration files in a location that will You might wish to keep the configuration files in a location that will
be backed up by your regular file system backup procedures. See be backed up by your regular file system backup procedures. See
<xref linkend="runtime-config-file-locations"> for how to relocate the <xref linkend="runtime-config-file-locations"/> for how to relocate the
configuration files. configuration files.
</para> </para>
@ -715,7 +715,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_wal/0
where it does so), there could be a long delay between the completion where it does so), there could be a long delay between the completion
of a transaction and its safe recording in archive storage. To put of a transaction and its safe recording in archive storage. To put
a limit on how old unarchived data can be, you can set a limit on how old unarchived data can be, you can set
<xref linkend="guc-archive-timeout"> to force the server to switch <xref linkend="guc-archive-timeout"/> to force the server to switch
to a new WAL segment file at least that often. Note that archived to a new WAL segment file at least that often. Note that archived
files that are archived early due to a forced switch are still the same files that are archived early due to a forced switch are still the same
length as completely full files. It is therefore unwise to set a very length as completely full files. It is therefore unwise to set a very
@ -729,13 +729,13 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_wal/0
<function>pg_switch_wal</function> if you want to ensure that a <function>pg_switch_wal</function> if you want to ensure that a
just-finished transaction is archived as soon as possible. Other utility just-finished transaction is archived as soon as possible. Other utility
functions related to WAL management are listed in <xref functions related to WAL management are listed in <xref
linkend="functions-admin-backup-table">. linkend="functions-admin-backup-table"/>.
</para> </para>
<para> <para>
When <varname>wal_level</varname> is <literal>minimal</literal> some SQL commands When <varname>wal_level</varname> is <literal>minimal</literal> some SQL commands
are optimized to avoid WAL logging, as described in <xref are optimized to avoid WAL logging, as described in <xref
linkend="populate-pitr">. If archiving or streaming replication were linkend="populate-pitr"/>. If archiving or streaming replication were
turned on during execution of one of these statements, WAL would not turned on during execution of one of these statements, WAL would not
contain enough information for archive recovery. (Crash recovery is contain enough information for archive recovery. (Crash recovery is
unaffected.) For this reason, <varname>wal_level</varname> can only be changed at unaffected.) For this reason, <varname>wal_level</varname> can only be changed at
@ -753,11 +753,11 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_wal/0
<para> <para>
The easiest way to perform a base backup is to use the The easiest way to perform a base backup is to use the
<xref linkend="app-pgbasebackup"> tool. It can create <xref linkend="app-pgbasebackup"/> tool. It can create
a base backup either as regular files or as a tar archive. If more a base backup either as regular files or as a tar archive. If more
flexibility than <xref linkend="app-pgbasebackup"> can provide is flexibility than <xref linkend="app-pgbasebackup"/> can provide is
required, you can also make a base backup using the low level API required, you can also make a base backup using the low level API
(see <xref linkend="backup-lowlevel-base-backup">). (see <xref linkend="backup-lowlevel-base-backup"/>).
</para> </para>
<para> <para>
@ -791,7 +791,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_wal/0
<para> <para>
The backup history file is just a small text file. It contains the The backup history file is just a small text file. It contains the
label string you gave to <xref linkend="app-pgbasebackup">, as well as label string you gave to <xref linkend="app-pgbasebackup"/>, as well as
the starting and ending times and WAL segments of the backup. the starting and ending times and WAL segments of the backup.
If you used the label to identify the associated dump file, If you used the label to identify the associated dump file,
then the archived history file is enough to tell you which dump file to then the archived history file is enough to tell you which dump file to
@ -814,7 +814,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_wal/0
<para> <para>
The procedure for making a base backup using the low level The procedure for making a base backup using the low level
APIs contains a few more steps than APIs contains a few more steps than
the <xref linkend="app-pgbasebackup"> method, but is relatively the <xref linkend="app-pgbasebackup"/> method, but is relatively
simple. It is very important that these steps are executed in simple. It is very important that these steps are executed in
sequence, and that the success of a step is verified before sequence, and that the success of a step is verified before
proceeding to the next step. proceeding to the next step.
@ -830,7 +830,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_wal/0
A non-exclusive low level backup is one that allows other A non-exclusive low level backup is one that allows other
concurrent backups to be running (both those started using concurrent backups to be running (both those started using
the same backup API and those started using the same backup API and those started using
<xref linkend="app-pgbasebackup">). <xref linkend="app-pgbasebackup"/>).
</para> </para>
<para> <para>
<orderedlist> <orderedlist>
@ -859,7 +859,7 @@ SELECT pg_start_backup('label', false, false);
required for the checkpoint will be spread out over a significant required for the checkpoint will be spread out over a significant
period of time, by default half your inter-checkpoint interval period of time, by default half your inter-checkpoint interval
(see the configuration parameter (see the configuration parameter
<xref linkend="guc-checkpoint-completion-target">). This is <xref linkend="guc-checkpoint-completion-target"/>). This is
usually what you want, because it minimizes the impact on query usually what you want, because it minimizes the impact on query
processing. If you want to start the backup as soon as processing. If you want to start the backup as soon as
possible, change the second parameter to <literal>true</literal>, which will possible, change the second parameter to <literal>true</literal>, which will
@ -879,7 +879,7 @@ SELECT pg_start_backup('label', false, false);
<application>pg_dumpall</application>). It is neither <application>pg_dumpall</application>). It is neither
necessary nor desirable to stop normal operation of the database necessary nor desirable to stop normal operation of the database
while you do this. See while you do this. See
<xref linkend="backup-lowlevel-base-backup-data"> for things to <xref linkend="backup-lowlevel-base-backup-data"/> for things to
consider during this backup. consider during this backup.
</para> </para>
</listitem> </listitem>
@ -989,7 +989,7 @@ SELECT pg_start_backup('label');
required for the checkpoint will be spread out over a significant required for the checkpoint will be spread out over a significant
period of time, by default half your inter-checkpoint interval period of time, by default half your inter-checkpoint interval
(see the configuration parameter (see the configuration parameter
<xref linkend="guc-checkpoint-completion-target">). This is <xref linkend="guc-checkpoint-completion-target"/>). This is
usually what you want, because it minimizes the impact on query usually what you want, because it minimizes the impact on query
processing. If you want to start the backup as soon as processing. If you want to start the backup as soon as
possible, use: possible, use:
@ -1007,7 +1007,7 @@ SELECT pg_start_backup('label', true);
<application>pg_dumpall</application>). It is neither <application>pg_dumpall</application>). It is neither
necessary nor desirable to stop normal operation of the database necessary nor desirable to stop normal operation of the database
while you do this. See while you do this. See
<xref linkend="backup-lowlevel-base-backup-data"> for things to <xref linkend="backup-lowlevel-base-backup-data"/> for things to
consider during this backup. consider during this backup.
</para> </para>
<para> <para>
@ -1119,7 +1119,7 @@ SELECT pg_stop_backup();
<filename>pg_snapshots/</filename>, <filename>pg_stat_tmp/</filename>, <filename>pg_snapshots/</filename>, <filename>pg_stat_tmp/</filename>,
and <filename>pg_subtrans/</filename> (but not the directories themselves) can be and <filename>pg_subtrans/</filename> (but not the directories themselves) can be
omitted from the backup as they will be initialized on postmaster startup. 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 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. directory then the contents of that directory can also be omitted.
</para> </para>
@ -1221,7 +1221,7 @@ SELECT pg_stop_backup();
<listitem> <listitem>
<para> <para>
Create a recovery command file <filename>recovery.conf</filename> in the cluster Create a recovery command file <filename>recovery.conf</filename> in the cluster
data directory (see <xref linkend="recovery-config">). You might data directory (see <xref linkend="recovery-config"/>). You might
also want to temporarily modify <filename>pg_hba.conf</filename> to prevent also want to temporarily modify <filename>pg_hba.conf</filename> to prevent
ordinary users from connecting until you are sure the recovery was successful. ordinary users from connecting until you are sure the recovery was successful.
</para> </para>
@ -1310,7 +1310,7 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
at the start of recovery for a file named something like at the start of recovery for a file named something like
<filename>00000001.history</filename>. This is also normal and does not <filename>00000001.history</filename>. This is also normal and does not
indicate a problem in simple recovery situations; see indicate a problem in simple recovery situations; see
<xref linkend="backup-timelines"> for discussion. <xref linkend="backup-timelines"/> for discussion.
</para> </para>
<para> <para>
@ -1440,7 +1440,7 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
<para> <para>
As with base backups, the easiest way to produce a standalone As with base backups, the easiest way to produce a standalone
hot backup is to use the <xref linkend="app-pgbasebackup"> hot backup is to use the <xref linkend="app-pgbasebackup"/>
tool. If you include the <literal>-X</literal> parameter when calling tool. If you include the <literal>-X</literal> parameter when calling
it, all the write-ahead 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 included in the backup automatically, and no special action is
@ -1548,7 +1548,7 @@ archive_command = 'local_backup_script.sh "%p" "%f"'
<tip> <tip>
<para> <para>
When using an <varname>archive_command</varname> script, it's desirable When using an <varname>archive_command</varname> script, it's desirable
to enable <xref linkend="guc-logging-collector">. to enable <xref linkend="guc-logging-collector"/>.
Any messages written to <systemitem>stderr</systemitem> from the script will then Any messages written to <systemitem>stderr</systemitem> from the script will then
appear in the database server log, allowing complex configurations to appear in the database server log, allowing complex configurations to
be diagnosed easily if they fail. be diagnosed easily if they fail.
@ -1567,7 +1567,7 @@ archive_command = 'local_backup_script.sh "%p" "%f"'
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
If a <xref linkend="sql-createdatabase"> If a <xref linkend="sql-createdatabase"/>
command is executed while a base backup is being taken, and then command is executed while a base backup is being taken, and then
the template database that the <command>CREATE DATABASE</command> copied the template database that the <command>CREATE DATABASE</command> copied
is modified while the base backup is still in progress, it is is modified while the base backup is still in progress, it is
@ -1580,7 +1580,7 @@ archive_command = 'local_backup_script.sh "%p" "%f"'
<listitem> <listitem>
<para> <para>
<xref linkend="sql-createtablespace"> <xref linkend="sql-createtablespace"/>
commands are WAL-logged with the literal absolute path, and will commands are WAL-logged with the literal absolute path, and will
therefore be replayed as tablespace creations with the same therefore be replayed as tablespace creations with the same
absolute path. This might be undesirable if the log is being absolute path. This might be undesirable if the log is being
@ -1603,8 +1603,8 @@ archive_command = 'local_backup_script.sh "%p" "%f"'
your system hardware and software, the risk of partial writes might your system hardware and software, the risk of partial writes might
be small enough to ignore, in which case you can significantly be small enough to ignore, in which case you can significantly
reduce the total volume of archived logs by turning off page reduce the total volume of archived logs by turning off page
snapshots using the <xref linkend="guc-full-page-writes"> snapshots using the <xref linkend="guc-full-page-writes"/>
parameter. (Read the notes and warnings in <xref linkend="wal"> parameter. (Read the notes and warnings in <xref linkend="wal"/>
before you do so.) Turning off page snapshots does not prevent before you do so.) Turning off page snapshots does not prevent
use of the logs for PITR operations. An area for future use of the logs for PITR operations. An area for future
development is to compress archived WAL data by removing development is to compress archived WAL data by removing

2
doc/src/sgml/bgworker.sgml
View File

@ -286,6 +286,6 @@ typedef struct BackgroundWorker
<para> <para>
The maximum number of registered background workers is limited by The maximum number of registered background workers is limited by
<xref linkend="guc-max-worker-processes">. <xref linkend="guc-max-worker-processes"/>.
</para> </para>
</chapter> </chapter>

8
doc/src/sgml/brin.sgml
View File

@ -95,7 +95,7 @@
<para> <para>
The core <productname>PostgreSQL</productname> distribution The core <productname>PostgreSQL</productname> distribution
includes the <acronym>BRIN</acronym> operator classes shown in includes the <acronym>BRIN</acronym> operator classes shown in
<xref linkend="brin-builtin-opclasses-table">. <xref linkend="brin-builtin-opclasses-table"/>.
</para> </para>
<para> <para>
@ -590,7 +590,7 @@ typedef struct BrinOpcInfo
To write an operator class for a data type that implements a totally To write an operator class for a data type that implements a totally
ordered set, it is possible to use the minmax support procedures ordered set, it is possible to use the minmax support procedures
alongside the corresponding operators, as shown in alongside the corresponding operators, as shown in
<xref linkend="brin-extensibility-minmax-table">. <xref linkend="brin-extensibility-minmax-table"/>.
All operator class members (procedures and operators) are mandatory. All operator class members (procedures and operators) are mandatory.
</para> </para>
@ -648,7 +648,7 @@ typedef struct BrinOpcInfo
To write an operator class for a complex data type which has values To write an operator class for a complex data type which has values
included within another type, it's possible to use the inclusion support included within another type, it's possible to use the inclusion support
procedures alongside the corresponding operators, as shown procedures alongside the corresponding operators, as shown
in <xref linkend="brin-extensibility-inclusion-table">. It requires in <xref linkend="brin-extensibility-inclusion-table"/>. It requires
only a single additional function, which can be written in any language. only a single additional function, which can be written in any language.
More functions can be defined for additional functionality. All operators More functions can be defined for additional functionality. All operators
are optional. Some operators require other operators, as shown as are optional. Some operators require other operators, as shown as
@ -821,7 +821,7 @@ typedef struct BrinOpcInfo
additional data types to be supported by defining extra sets additional data types to be supported by defining extra sets
of operators. Inclusion operator class operator strategies are dependent of operators. Inclusion operator class operator strategies are dependent
on another operator strategy as shown in on another operator strategy as shown in
<xref linkend="brin-extensibility-inclusion-table">, or the same <xref linkend="brin-extensibility-inclusion-table"/>, or the same
operator strategy as themselves. They require the dependency operator strategy as themselves. They require the dependency
operator to be defined with the <literal>STORAGE</literal> data type as the operator to be defined with the <literal>STORAGE</literal> data type as the
left-hand-side argument and the other supported data type to be the left-hand-side argument and the other supported data type to be the

202
doc/src/sgml/catalogs.sgml
View File

@ -27,7 +27,7 @@
<title>Overview</title> <title>Overview</title>
<para> <para>
<xref linkend="catalog-table"> lists the system catalogs. <xref linkend="catalog-table"/> lists the system catalogs.
More detailed documentation of each catalog follows below. More detailed documentation of each catalog follows below.
</para> </para>
@ -567,8 +567,8 @@
<para> <para>
New aggregate functions are registered with the <xref New aggregate functions are registered with the <xref
linkend="sql-createaggregate"> linkend="sql-createaggregate"/>
command. See <xref linkend="xaggr"> for more information about command. See <xref linkend="xaggr"/> for more information about
writing aggregate functions and the meaning of the transition writing aggregate functions and the meaning of the transition
functions, etc. functions, etc.
</para> </para>
@ -588,7 +588,7 @@
relation access methods. There is one row for each access method supported relation access methods. There is one row for each access method supported
by the system. by the system.
Currently, only indexes have access methods. The requirements for index Currently, only indexes have access methods. The requirements for index
access methods are discussed in detail in <xref linkend="indexam">. access methods are discussed in detail in <xref linkend="indexam"/>.
</para> </para>
<table> <table>
@ -649,7 +649,7 @@
methods. That data is now only directly visible at the C code level. methods. That data is now only directly visible at the C code level.
However, <function>pg_index_column_has_property()</function> and related However, <function>pg_index_column_has_property()</function> and related
functions have been added to allow SQL queries to inspect index access functions have been added to allow SQL queries to inspect index access
method properties; see <xref linkend="functions-info-catalog-table">. method properties; see <xref linkend="functions-info-catalog-table"/>.
</para> </para>
</note> </note>
@ -1034,7 +1034,7 @@
<entry> <entry>
<structfield>attstattarget</structfield> controls the level of detail <structfield>attstattarget</structfield> controls the level of detail
of statistics accumulated for this column by of statistics accumulated for this column by
<xref linkend="sql-analyze">. <xref linkend="sql-analyze"/>.
A zero value indicates that no statistics should be collected. A zero value indicates that no statistics should be collected.
A negative value says to use the system default statistics target. A negative value says to use the system default statistics target.
The exact meaning of positive values is data type-dependent. The exact meaning of positive values is data type-dependent.
@ -1270,7 +1270,7 @@
</para> </para>
<para> <para>
<xref linkend="user-manag"> contains detailed information about user and <xref linkend="user-manag"/> contains detailed information about user and
privilege management. privilege management.
</para> </para>
@ -1356,7 +1356,7 @@
<entry><type>bool</type></entry> <entry><type>bool</type></entry>
<entry> <entry>
Role bypasses every row level security policy, see Role bypasses every row level security policy, see
<xref linkend="ddl-rowsecurity"> for more information. <xref linkend="ddl-rowsecurity"/> for more information.
</entry> </entry>
</row> </row>
@ -1964,8 +1964,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry></entry> <entry></entry>
<entry> <entry>
Access privileges; see Access privileges; see
<xref linkend="sql-grant"> and <xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"> <xref linkend="sql-revoke"/>
for details for details
</entry> </entry>
</row> </row>
@ -2015,7 +2015,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
The catalog <structname>pg_collation</structname> describes the The catalog <structname>pg_collation</structname> describes the
available collations, which are essentially mappings from an SQL available collations, which are essentially mappings from an SQL
name to operating system locale categories. name to operating system locale categories.
See <xref linkend="collation"> for more information. See <xref linkend="collation"/> for more information.
</para> </para>
<table> <table>
@ -2424,7 +2424,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_conversion</structname> describes The catalog <structname>pg_conversion</structname> describes
encoding conversion procedures. See <xref linkend="sql-createconversion"> encoding conversion procedures. See <xref linkend="sql-createconversion"/>
for more information. for more information.
</para> </para>
@ -2516,8 +2516,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_database</structname> stores information about The catalog <structname>pg_database</structname> stores information about
the available databases. Databases are created with the <xref the available databases. Databases are created with the <xref
linkend="sql-createdatabase"> command. linkend="sql-createdatabase"/> command.
Consult <xref linkend="managing-databases"> for details about the meaning Consult <xref linkend="managing-databases"/> for details about the meaning
of some of the parameters. of some of the parameters.
</para> </para>
@ -2675,8 +2675,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry></entry> <entry></entry>
<entry> <entry>
Access privileges; see Access privileges; see
<xref linkend="sql-grant"> and <xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"> <xref linkend="sql-revoke"/>
for details for details
</entry> </entry>
</row> </row>
@ -3053,7 +3053,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_description</structname> stores optional descriptions The catalog <structname>pg_description</structname> stores optional descriptions
(comments) for each database object. Descriptions can be manipulated (comments) for each database object. Descriptions can be manipulated
with the <xref linkend="sql-comment"> command and viewed with with the <xref linkend="sql-comment"/> command and viewed with
<application>psql</application>'s <literal>\d</literal> commands. <application>psql</application>'s <literal>\d</literal> commands.
Descriptions of many built-in system objects are provided in the initial Descriptions of many built-in system objects are provided in the initial
contents of <structname>pg_description</structname>. contents of <structname>pg_description</structname>.
@ -3208,7 +3208,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_event_trigger</structname> stores event triggers. The catalog <structname>pg_event_trigger</structname> stores event triggers.
See <xref linkend="event-triggers"> for more information. See <xref linkend="event-triggers"/> for more information.
</para> </para>
<table> <table>
@ -3258,7 +3258,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry><type>char</type></entry> <entry><type>char</type></entry>
<entry></entry> <entry></entry>
<entry> <entry>
Controls in which <xref linkend="guc-session-replication-role"> modes Controls in which <xref linkend="guc-session-replication-role"/> modes
the event trigger fires. the event trigger fires.
<literal>O</literal> = trigger fires in <quote>origin</quote> and <quote>local</quote> modes, <literal>O</literal> = trigger fires in <quote>origin</quote> and <quote>local</quote> modes,
<literal>D</literal> = trigger is disabled, <literal>D</literal> = trigger is disabled,
@ -3291,7 +3291,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_extension</structname> stores information The catalog <structname>pg_extension</structname> stores information
about the installed extensions. See <xref linkend="extend-extensions"> about the installed extensions. See <xref linkend="extend-extensions"/>
for details about extensions. for details about extensions.
</para> </para>
@ -3463,8 +3463,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry></entry> <entry></entry>
<entry> <entry>
Access privileges; see Access privileges; see
<xref linkend="sql-grant"> and <xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"> <xref linkend="sql-revoke"/>
for details for details
</entry> </entry>
</row> </row>
@ -3559,8 +3559,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry></entry> <entry></entry>
<entry> <entry>
Access privileges; see Access privileges; see
<xref linkend="sql-grant"> and <xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"> <xref linkend="sql-revoke"/>
for details for details
</entry> </entry>
</row> </row>
@ -4011,8 +4011,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry></entry> <entry></entry>
<entry> <entry>
The initial access privileges; see The initial access privileges; see
<xref linkend="sql-grant"> and <xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"> <xref linkend="sql-revoke"/>
for details for details
</entry> </entry>
</row> </row>
@ -4034,8 +4034,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_language</structname> registers The catalog <structname>pg_language</structname> registers
languages in which you can write functions or stored procedures. languages in which you can write functions or stored procedures.
See <xref linkend="sql-createlanguage"> See <xref linkend="sql-createlanguage"/>
and <xref linkend="xplang"> for more information about language handlers. and <xref linkend="xplang"/> for more information about language handlers.
</para> </para>
<table> <table>
@ -4117,7 +4117,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry> <entry>
This references a function that is responsible for executing This references a function that is responsible for executing
<quote>inline</quote> anonymous code blocks <quote>inline</quote> anonymous code blocks
(<xref linkend="sql-do"> blocks). (<xref linkend="sql-do"/> blocks).
Zero if inline blocks are not supported. Zero if inline blocks are not supported.
</entry> </entry>
</row> </row>
@ -4139,8 +4139,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry></entry> <entry></entry>
<entry> <entry>
Access privileges; see Access privileges; see
<xref linkend="sql-grant"> and <xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"> <xref linkend="sql-revoke"/>
for details for details
</entry> </entry>
</row> </row>
@ -4279,8 +4279,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry></entry> <entry></entry>
<entry> <entry>
Access privileges; see Access privileges; see
<xref linkend="sql-grant"> and <xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"> <xref linkend="sql-revoke"/>
for details for details
</entry> </entry>
</row> </row>
@ -4346,8 +4346,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry></entry> <entry></entry>
<entry> <entry>
Access privileges; see Access privileges; see
<xref linkend="sql-grant"> and <xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"> <xref linkend="sql-revoke"/>
for details for details
</entry> </entry>
</row> </row>
@ -4377,7 +4377,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
</para> </para>
<para> <para>
Operator classes are described at length in <xref linkend="xindex">. Operator classes are described at length in <xref linkend="xindex"/>.
</para> </para>
<table> <table>
@ -4481,8 +4481,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_operator</structname> stores information about operators. The catalog <structname>pg_operator</structname> stores information about operators.
See <xref linkend="sql-createoperator"> See <xref linkend="sql-createoperator"/>
and <xref linkend="xoper"> for more information. and <xref linkend="xoper"/> for more information.
</para> </para>
<table> <table>
@ -4639,7 +4639,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
</para> </para>
<para> <para>
Operator families are described at length in <xref linkend="xindex">. Operator families are described at length in <xref linkend="xindex"/>.
</para> </para>
<table> <table>
@ -5040,8 +5040,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_proc</structname> stores information about functions (or procedures). The catalog <structname>pg_proc</structname> stores information about functions (or procedures).
See <xref linkend="sql-createfunction"> See <xref linkend="sql-createfunction"/>
and <xref linkend="xfunc"> for more information. and <xref linkend="xfunc"/> for more information.
</para> </para>
<para> <para>
@ -5106,7 +5106,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry><type>float4</type></entry> <entry><type>float4</type></entry>
<entry></entry> <entry></entry>
<entry>Estimated execution cost (in units of <entry>Estimated execution cost (in units of
<xref linkend="guc-cpu-operator-cost">); if <structfield>proretset</structfield>, <xref linkend="guc-cpu-operator-cost"/>); if <structfield>proretset</structfield>,
this is cost per row returned</entry> this is cost per row returned</entry>
</row> </row>
@ -5130,7 +5130,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry><type>regproc</type></entry> <entry><type>regproc</type></entry>
<entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry> <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
<entry>Calls to this function can be simplified by this other function <entry>Calls to this function can be simplified by this other function
(see <xref linkend="xfunc-transform-functions">)</entry> (see <xref linkend="xfunc-transform-functions"/>)</entry>
</row> </row>
<row> <row>
@ -5359,8 +5359,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry></entry> <entry></entry>
<entry> <entry>
Access privileges; see Access privileges; see
<xref linkend="sql-grant"> and <xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"> <xref linkend="sql-revoke"/>
for details for details
</entry> </entry>
</row> </row>
@ -5390,7 +5390,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_publication</structname> contains all The catalog <structname>pg_publication</structname> contains all
publications created in the database. For more on publications see publications created in the database. For more on publications see
<xref linkend="logical-replication-publication">. <xref linkend="logical-replication-publication"/>.
</para> </para>
<table> <table>
@ -5475,7 +5475,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_publication_rel</structname> contains the The catalog <structname>pg_publication_rel</structname> contains the
mapping between relations and publications in the database. This is a mapping between relations and publications in the database. This is a
many-to-many mapping. See also <xref linkend="view-pg-publication-tables"> many-to-many mapping. See also <xref linkend="view-pg-publication-tables"/>
for a more user-friendly view of this information. for a more user-friendly view of this information.
</para> </para>
@ -5605,7 +5605,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The <structname>pg_replication_origin</structname> catalog contains The <structname>pg_replication_origin</structname> catalog contains
all replication origins created. For more on replication origins all replication origins created. For more on replication origins
see <xref linkend="replication-origins">. see <xref linkend="replication-origins"/>.
</para> </para>
<table> <table>
@ -5705,7 +5705,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry><type>char</type></entry> <entry><type>char</type></entry>
<entry></entry> <entry></entry>
<entry> <entry>
Controls in which <xref linkend="guc-session-replication-role"> modes Controls in which <xref linkend="guc-session-replication-role"/> modes
the rule fires. the rule fires.
<literal>O</literal> = rule fires in <quote>origin</quote> and <quote>local</quote> modes, <literal>O</literal> = rule fires in <quote>origin</quote> and <quote>local</quote> modes,
<literal>D</literal> = rule is disabled, <literal>D</literal> = rule is disabled,
@ -5765,8 +5765,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_seclabel</structname> stores security The catalog <structname>pg_seclabel</structname> stores security
labels on database objects. Security labels can be manipulated labels on database objects. Security labels can be manipulated
with the <xref linkend="sql-security-label"> command. For an easier with the <xref linkend="sql-security-label"/> command. For an easier
way to view security labels, see <xref linkend="view-pg-seclabels">. way to view security labels, see <xref linkend="view-pg-seclabels"/>.
</para> </para>
<para> <para>
@ -6093,7 +6093,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_shdescription</structname> stores optional The catalog <structname>pg_shdescription</structname> stores optional
descriptions (comments) for shared database objects. Descriptions can be descriptions (comments) for shared database objects. Descriptions can be
manipulated with the <xref linkend="sql-comment"> command and viewed with manipulated with the <xref linkend="sql-comment"/> command and viewed with
<application>psql</application>'s <literal>\d</literal> commands. <application>psql</application>'s <literal>\d</literal> commands.
</para> </para>
@ -6160,8 +6160,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_shseclabel</structname> stores security The catalog <structname>pg_shseclabel</structname> stores security
labels on shared database objects. Security labels can be manipulated labels on shared database objects. Security labels can be manipulated
with the <xref linkend="sql-security-label"> command. For an easier with the <xref linkend="sql-security-label"/> command. For an easier
way to view security labels, see <xref linkend="view-pg-seclabels">. way to view security labels, see <xref linkend="view-pg-seclabels"/>.
</para> </para>
<para> <para>
@ -6228,7 +6228,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_statistic</structname> stores The catalog <structname>pg_statistic</structname> stores
statistical data about the contents of the database. Entries are statistical data about the contents of the database. Entries are
created by <xref linkend="sql-analyze"> created by <xref linkend="sql-analyze"/>
and subsequently used by the query planner. Note that all the and subsequently used by the query planner. Note that all the
statistical data is inherently approximate, even assuming that it statistical data is inherently approximate, even assuming that it
is up-to-date. is up-to-date.
@ -6408,7 +6408,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
The catalog <structname>pg_statistic_ext</structname> The catalog <structname>pg_statistic_ext</structname>
holds extended planner statistics. holds extended planner statistics.
Each row in this catalog corresponds to a <firstterm>statistics object</firstterm> Each row in this catalog corresponds to a <firstterm>statistics object</firstterm>
created with <xref linkend="sql-createstatistics">. created with <xref linkend="sql-createstatistics"/>.
</para> </para>
<table> <table>
@ -6521,7 +6521,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_subscription</structname> contains all existing The catalog <structname>pg_subscription</structname> contains all existing
logical replication subscriptions. For more information about logical logical replication subscriptions. For more information about logical
replication see <xref linkend="logical-replication">. replication see <xref linkend="logical-replication"/>.
</para> </para>
<para> <para>
@ -6616,7 +6616,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry></entry> <entry></entry>
<entry>Array of subscribed publication names. These reference the <entry>Array of subscribed publication names. These reference the
publications on the publisher server. For more on publications publications on the publisher server. For more on publications
see <xref linkend="logical-replication-publication">. see <xref linkend="logical-replication-publication"/>.
</entry> </entry>
</row> </row>
</tbody> </tbody>
@ -6758,8 +6758,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry></entry> <entry></entry>
<entry> <entry>
Access privileges; see Access privileges; see
<xref linkend="sql-grant"> and <xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"> <xref linkend="sql-revoke"/>
for details for details
</entry> </entry>
</row> </row>
@ -6788,7 +6788,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_transform</structname> stores information about The catalog <structname>pg_transform</structname> stores information about
transforms, which are a mechanism to adapt data types to procedural transforms, which are a mechanism to adapt data types to procedural
languages. See <xref linkend="sql-createtransform"> for more information. languages. See <xref linkend="sql-createtransform"/> for more information.
</para> </para>
<table> <table>
@ -6856,7 +6856,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_trigger</structname> stores triggers on tables The catalog <structname>pg_trigger</structname> stores triggers on tables
and views. and views.
See <xref linkend="sql-createtrigger"> See <xref linkend="sql-createtrigger"/>
for more information. for more information.
</para> </para>
@ -6914,7 +6914,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry><type>char</type></entry> <entry><type>char</type></entry>
<entry></entry> <entry></entry>
<entry> <entry>
Controls in which <xref linkend="guc-session-replication-role"> modes Controls in which <xref linkend="guc-session-replication-role"/> modes
the trigger fires. the trigger fires.
<literal>O</literal> = trigger fires in <quote>origin</quote> and <quote>local</quote> modes, <literal>O</literal> = trigger fires in <quote>origin</quote> and <quote>local</quote> modes,
<literal>D</literal> = trigger is disabled, <literal>D</literal> = trigger is disabled,
@ -7066,7 +7066,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
<productname>PostgreSQL</productname>'s text search features are <productname>PostgreSQL</productname>'s text search features are
described at length in <xref linkend="textsearch">. described at length in <xref linkend="textsearch"/>.
</para> </para>
<table> <table>
@ -7141,7 +7141,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
<productname>PostgreSQL</productname>'s text search features are <productname>PostgreSQL</productname>'s text search features are
described at length in <xref linkend="textsearch">. described at length in <xref linkend="textsearch"/>.
</para> </para>
<table> <table>
@ -7212,7 +7212,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
<productname>PostgreSQL</productname>'s text search features are <productname>PostgreSQL</productname>'s text search features are
described at length in <xref linkend="textsearch">. described at length in <xref linkend="textsearch"/>.
</para> </para>
<table> <table>
@ -7295,7 +7295,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
<productname>PostgreSQL</productname>'s text search features are <productname>PostgreSQL</productname>'s text search features are
described at length in <xref linkend="textsearch">. described at length in <xref linkend="textsearch"/>.
</para> </para>
<table> <table>
@ -7392,7 +7392,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
<productname>PostgreSQL</productname>'s text search features are <productname>PostgreSQL</productname>'s text search features are
described at length in <xref linkend="textsearch">. described at length in <xref linkend="textsearch"/>.
</para> </para>
<table> <table>
@ -7461,9 +7461,9 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The catalog <structname>pg_type</structname> stores information about data The catalog <structname>pg_type</structname> stores information about data
types. Base types and enum types (scalar types) are created with types. Base types and enum types (scalar types) are created with
<xref linkend="sql-createtype">, and <xref linkend="sql-createtype"/>, and
domains with domains with
<xref linkend="sql-createdomain">. <xref linkend="sql-createdomain"/>.
A composite type is automatically created for each table in the database, to A composite type is automatically created for each table in the database, to
represent the row structure of the table. It is also possible to create represent the row structure of the table. It is also possible to create
composite types with <command>CREATE TYPE AS</command>. composite types with <command>CREATE TYPE AS</command>.
@ -7567,7 +7567,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<structfield>typcategory</structfield> is an arbitrary classification <structfield>typcategory</structfield> is an arbitrary classification
of data types that is used by the parser to determine which implicit of data types that is used by the parser to determine which implicit
casts should be <quote>preferred</quote>. casts should be <quote>preferred</quote>.
See <xref linkend="catalog-typcategory-table">. See <xref linkend="catalog-typcategory-table"/>.
</entry> </entry>
</row> </row>
@ -7871,8 +7871,8 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry></entry> <entry></entry>
<entry> <entry>
Access privileges; see Access privileges; see
<xref linkend="sql-grant"> and <xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"> <xref linkend="sql-revoke"/>
for details for details
</entry> </entry>
</row> </row>
@ -7881,7 +7881,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
</table> </table>
<para> <para>
<xref linkend="catalog-typcategory-table"> lists the system-defined values <xref linkend="catalog-typcategory-table"/> lists the system-defined values
of <structfield>typcategory</structfield>. Any future additions to this list will of <structfield>typcategory</structfield>. Any future additions to this list will
also be upper-case ASCII letters. All other ASCII characters are reserved also be upper-case ASCII letters. All other ASCII characters are reserved
for user-defined categories. for user-defined categories.
@ -8043,7 +8043,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
</para> </para>
<para> <para>
The information schema (<xref linkend="information-schema">) provides The information schema (<xref linkend="information-schema"/>) provides
an alternative set of views which overlap the functionality of the system an alternative set of views which overlap the functionality of the system
views. Since the information schema is SQL-standard whereas the views views. Since the information schema is SQL-standard whereas the views
described here are <productname>PostgreSQL</productname>-specific, described here are <productname>PostgreSQL</productname>-specific,
@ -8052,11 +8052,11 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
</para> </para>
<para> <para>
<xref linkend="view-table"> lists the system views described here. <xref linkend="view-table"/> lists the system views described here.
More detailed documentation of each view follows below. More detailed documentation of each view follows below.
There are some additional views that provide access to the results of There are some additional views that provide access to the results of
the statistics collector; they are described in <xref the statistics collector; they are described in <xref
linkend="monitoring-stats-views-table">. linkend="monitoring-stats-views-table"/>.
</para> </para>
<para> <para>
@ -8389,7 +8389,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
be used by software packages that want to interface to be used by software packages that want to interface to
<productname>PostgreSQL</productname> to facilitate finding the required header <productname>PostgreSQL</productname> to facilitate finding the required header
files and libraries. It provides the same basic information as the files and libraries. It provides the same basic information as the
<xref linkend="app-pgconfig"> <productname>PostgreSQL</productname> client <xref linkend="app-pgconfig"/> <productname>PostgreSQL</productname> client
application. application.
</para> </para>
@ -8440,7 +8440,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
via the <xref linkend="sql-declare"> via the <xref linkend="sql-declare"/>
statement in SQL statement in SQL
</para> </para>
</listitem> </listitem>
@ -8448,14 +8448,14 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<listitem> <listitem>
<para> <para>
via the Bind message in the frontend/backend protocol, as via the Bind message in the frontend/backend protocol, as
described in <xref linkend="protocol-flow-ext-query"> described in <xref linkend="protocol-flow-ext-query"/>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
via the Server Programming Interface (SPI), as described in via the Server Programming Interface (SPI), as described in
<xref linkend="spi-interface"> <xref linkend="spi-interface"/>
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -8648,7 +8648,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
</para> </para>
<para> <para>
See <xref linkend="config-setting"> for more information about the various See <xref linkend="config-setting"/> for more information about the various
ways to change run-time parameters. ways to change run-time parameters.
</para> </para>
@ -8813,7 +8813,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
</para> </para>
<para> <para>
See <xref linkend="client-authentication"> for more information about See <xref linkend="client-authentication"/> for more information about
client authentication configuration. client authentication configuration.
</para> </para>
</sect1> </sect1>
@ -8890,7 +8890,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<para> <para>
The view <structname>pg_locks</structname> provides access to The view <structname>pg_locks</structname> provides access to
information about the locks held by active processes within the information about the locks held by active processes within the
database server. See <xref linkend="mvcc"> for more discussion database server. See <xref linkend="mvcc"/> for more discussion
of locking. of locking.
</para> </para>
@ -9053,7 +9053,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry><type>text</type></entry> <entry><type>text</type></entry>
<entry></entry> <entry></entry>
<entry>Name of the lock mode held or desired by this process (see <xref <entry>Name of the lock mode held or desired by this process (see <xref
linkend="locking-tables"> and <xref linkend="xact-serializable">)</entry> linkend="locking-tables"/> and <xref linkend="xact-serializable"/>)</entry>
</row> </row>
<row> <row>
<entry><structfield>granted</structfield></entry> <entry><structfield>granted</structfield></entry>
@ -9164,7 +9164,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
queues, nor information about which processes are parallel workers running queues, nor information about which processes are parallel workers running
on behalf of which other client sessions. It is better to use on behalf of which other client sessions. It is better to use
the <function>pg_blocking_pids()</function> function the <function>pg_blocking_pids()</function> function
(see <xref linkend="functions-info-session-table">) to identify which (see <xref linkend="functions-info-session-table"/>) to identify which
process(es) a waiting process is blocked behind. process(es) a waiting process is blocked behind.
</para> </para>
@ -9369,7 +9369,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
<para> <para>
The <structname>pg_prepared_statements</structname> view displays The <structname>pg_prepared_statements</structname> view displays
all the prepared statements that are available in the current all the prepared statements that are available in the current
session. See <xref linkend="sql-prepare"> for more information about prepared session. See <xref linkend="sql-prepare"/> for more information about prepared
statements. statements.
</para> </para>
@ -9377,7 +9377,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
<structname>pg_prepared_statements</structname> contains one row <structname>pg_prepared_statements</structname> contains one row
for each prepared statement. Rows are added to the view when a new for each prepared statement. Rows are added to the view when a new
prepared statement is created and removed when a prepared statement prepared statement is created and removed when a prepared statement
is released (for example, via the <xref linkend="sql-deallocate"> command). is released (for example, via the <xref linkend="sql-deallocate"/> command).
</para> </para>
<table> <table>
@ -9457,7 +9457,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
<para> <para>
The view <structname>pg_prepared_xacts</structname> displays The view <structname>pg_prepared_xacts</structname> displays
information about transactions that are currently prepared for two-phase information about transactions that are currently prepared for two-phase
commit (see <xref linkend="sql-prepare-transaction"> for details). commit (see <xref linkend="sql-prepare-transaction"/> for details).
</para> </para>
<para> <para>
@ -9601,7 +9601,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
The <structname>pg_replication_origin_status</structname> view The <structname>pg_replication_origin_status</structname> view
contains information about how far replay for a certain origin has contains information about how far replay for a certain origin has
progressed. For more on replication origins progressed. For more on replication origins
see <xref linkend="replication-origins">. see <xref linkend="replication-origins"/>.
</para> </para>
<table> <table>
@ -9670,7 +9670,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
<para> <para>
For more on replication slots, For more on replication slots,
see <xref linkend="streaming-replication-slots"> and <xref linkend="logicaldecoding">. see <xref linkend="streaming-replication-slots"/> and <xref linkend="logicaldecoding"/>.
</para> </para>
<table> <table>
@ -9917,7 +9917,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
<entry></entry> <entry></entry>
<entry> <entry>
Role bypasses every row level security policy, see Role bypasses every row level security policy, see
<xref linkend="ddl-rowsecurity"> for more information. <xref linkend="ddl-rowsecurity"/> for more information.
</entry> </entry>
</row> </row>
@ -10203,8 +10203,8 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
<para> <para>
The view <structname>pg_settings</structname> provides access to The view <structname>pg_settings</structname> provides access to
run-time parameters of the server. It is essentially an alternative run-time parameters of the server. It is essentially an alternative
interface to the <xref linkend="sql-show"> interface to the <xref linkend="sql-show"/>
and <xref linkend="sql-set"> commands. and <xref linkend="sql-set"/> commands.
It also provides access to some facts about each parameter that are It also provides access to some facts about each parameter that are
not directly available from <command>SHOW</command>, such as minimum and not directly available from <command>SHOW</command>, such as minimum and
maximum values. maximum values.
@ -10441,7 +10441,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
</variablelist> </variablelist>
<para> <para>
See <xref linkend="config-setting"> for more information about the various See <xref linkend="config-setting"/> for more information about the various
ways to change these parameters. ways to change these parameters.
</para> </para>
@ -10449,7 +10449,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
The <structname>pg_settings</structname> view cannot be inserted into or The <structname>pg_settings</structname> view cannot be inserted into or
deleted from, but it can be updated. An <command>UPDATE</command> applied deleted from, but it can be updated. An <command>UPDATE</command> applied
to a row of <structname>pg_settings</structname> is equivalent to executing to a row of <structname>pg_settings</structname> is equivalent to executing
the <xref linkend="sql-set"> command on that named the <xref linkend="sql-set"/> command on that named
parameter. The change only affects the value used by the current parameter. The change only affects the value used by the current
session. If an <command>UPDATE</command> is issued within a transaction session. If an <command>UPDATE</command> is issued within a transaction
that is later aborted, the effects of the <command>UPDATE</command> command that is later aborted, the effects of the <command>UPDATE</command> command
@ -10543,7 +10543,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
<entry></entry> <entry></entry>
<entry> <entry>
User bypasses every row level security policy, see User bypasses every row level security policy, see
<xref linkend="ddl-rowsecurity"> for more information. <xref linkend="ddl-rowsecurity"/> for more information.
</entry> </entry>
</row> </row>
@ -10763,7 +10763,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
The maximum number of entries in the array fields can be controlled on a The maximum number of entries in the array fields can be controlled on a
column-by-column basis using the <command>ALTER TABLE SET STATISTICS</command> column-by-column basis using the <command>ALTER TABLE SET STATISTICS</command>
command, or globally by setting the command, or globally by setting the
<xref linkend="guc-default-statistics-target"> run-time parameter. <xref linkend="guc-default-statistics-target"/> run-time parameter.
</para> </para>
</sect1> </sect1>
@ -10858,7 +10858,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
The view <structname>pg_timezone_abbrevs</structname> provides a list The view <structname>pg_timezone_abbrevs</structname> provides a list
of time zone abbreviations that are currently recognized by the datetime of time zone abbreviations that are currently recognized by the datetime
input routines. The contents of this view change when the input routines. The contents of this view change when the
<xref linkend="guc-timezone-abbreviations"> run-time parameter is modified. <xref linkend="guc-timezone-abbreviations"/> run-time parameter is modified.
</para> </para>
<table> <table>
@ -10895,7 +10895,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
<para> <para>
While most timezone abbreviations represent fixed offsets from UTC, While most timezone abbreviations represent fixed offsets from UTC,
there are some that have historically varied in value there are some that have historically varied in value
(see <xref linkend="datetime-config-files"> for more information). (see <xref linkend="datetime-config-files"/> for more information).
In such cases this view presents their current meaning. In such cases this view presents their current meaning.
</para> </para>
@ -11025,7 +11025,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
<entry><type>bool</type></entry> <entry><type>bool</type></entry>
<entry> <entry>
User bypasses every row level security policy, see User bypasses every row level security policy, see
<xref linkend="ddl-rowsecurity"> for more information. <xref linkend="ddl-rowsecurity"/> for more information.
</entry> </entry>
</row> </row>

36
doc/src/sgml/charset.sgml
View File

@ -15,8 +15,8 @@
Using the locale features of the operating system to provide Using the locale features of the operating system to provide
locale-specific collation order, number formatting, translated locale-specific collation order, number formatting, translated
messages, and other aspects. messages, and other aspects.
This is covered in <xref linkend="locale"> and This is covered in <xref linkend="locale"/> and
<xref linkend="collation">. <xref linkend="collation"/>.
</para> </para>
</listitem> </listitem>
@ -25,7 +25,7 @@
Providing a number of different character sets to support storing text Providing a number of different character sets to support storing text
in all kinds of languages, and providing character set translation in all kinds of languages, and providing character set translation
between client and server. between client and server.
This is covered in <xref linkend="multibyte">. This is covered in <xref linkend="multibyte"/>.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -146,7 +146,7 @@ initdb --locale=sv_SE
the sort order of indexes, so they must be kept fixed, or indexes on the sort order of indexes, so they must be kept fixed, or indexes on
text columns would become corrupt. text columns would become corrupt.
(But you can alleviate this restriction using collations, as discussed (But you can alleviate this restriction using collations, as discussed
in <xref linkend="collation">.) in <xref linkend="collation"/>.)
The default values for these The default values for these
categories are determined when <command>initdb</command> is run, and categories are determined when <command>initdb</command> is run, and
those values are used when new databases are created, unless those values are used when new databases are created, unless
@ -157,7 +157,7 @@ initdb --locale=sv_SE
The other locale categories can be changed whenever desired The other locale categories can be changed whenever desired
by setting the server configuration parameters by setting the server configuration parameters
that have the same name as the locale categories (see <xref that have the same name as the locale categories (see <xref
linkend="runtime-config-client-format"> for details). The values linkend="runtime-config-client-format"/> for details). The values
that are chosen by <command>initdb</command> are actually only written that are chosen by <command>initdb</command> are actually only written
into the configuration file <filename>postgresql.conf</filename> to into the configuration file <filename>postgresql.conf</filename> to
serve as defaults when the server is started. If you remove these serve as defaults when the server is started. If you remove these
@ -267,10 +267,10 @@ initdb --locale=sv_SE
with <literal>LIKE</literal> clauses under a non-C locale, several custom with <literal>LIKE</literal> clauses under a non-C locale, several custom
operator classes exist. These allow the creation of an index that operator classes exist. These allow the creation of an index that
performs a strict character-by-character comparison, ignoring performs a strict character-by-character comparison, ignoring
locale comparison rules. Refer to <xref linkend="indexes-opclass"> locale comparison rules. Refer to <xref linkend="indexes-opclass"/>
for more information. Another approach is to create indexes using for more information. Another approach is to create indexes using
the <literal>C</literal> collation, as discussed in the <literal>C</literal> collation, as discussed in
<xref linkend="collation">. <xref linkend="collation"/>.
</para> </para>
</sect2> </sect2>
@ -316,7 +316,7 @@ initdb --locale=sv_SE
<productname>PostgreSQL</productname> speak their preferred language well. <productname>PostgreSQL</productname> speak their preferred language well.
If messages in your language are currently not available or not fully If messages in your language are currently not available or not fully
translated, your assistance would be appreciated. If you want to translated, your assistance would be appreciated. If you want to
help, refer to <xref linkend="nls"> or write to the developers' help, refer to <xref linkend="nls"/> or write to the developers'
mailing list. mailing list.
</para> </para>
</sect2> </sect2>
@ -524,7 +524,7 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR";
these under one concept than to create another infrastructure for these under one concept than to create another infrastructure for
setting <symbol>LC_CTYPE</symbol> per expression.) Also, setting <symbol>LC_CTYPE</symbol> per expression.) Also,
a <literal>libc</literal> collation a <literal>libc</literal> collation
is tied to a character set encoding (see <xref linkend="multibyte">). is tied to a character set encoding (see <xref linkend="multibyte"/>).
The same collation name may exist for different encodings. The same collation name may exist for different encodings.
</para> </para>
@ -605,7 +605,7 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR";
for <symbol>LC_COLLATE</symbol> and <symbol>LC_CTYPE</symbol>, or if new for <symbol>LC_COLLATE</symbol> and <symbol>LC_CTYPE</symbol>, or if new
locales are installed in the operating system after the database system locales are installed in the operating system after the database system
was initialized, then a new collation may be created using was initialized, then a new collation may be created using
the <xref linkend="sql-createcollation"> command. the <xref linkend="sql-createcollation"/> command.
New operating system locales can also be imported en masse using New operating system locales can also be imported en masse using
the <link linkend="functions-admin-collation"><function>pg_import_system_collations()</function></link> function. the <link linkend="functions-admin-collation"><function>pg_import_system_collations()</function></link> function.
</para> </para>
@ -702,7 +702,7 @@ SELECT a COLLATE "C" &lt; b COLLATE "POSIX" FROM test1;
<para> <para>
If the standard and predefined collations are not sufficient, users can If the standard and predefined collations are not sufficient, users can
create their own collation objects using the SQL create their own collation objects using the SQL
command <xref linkend="sql-createcollation">. command <xref linkend="sql-createcollation"/>.
</para> </para>
<para> <para>
@ -730,7 +730,7 @@ CREATE COLLATION german (provider = libc, locale = 'de_DE');
defined in the operating system when the database instance is defined in the operating system when the database instance is
initialized, it is not often necessary to manually create new ones. initialized, it is not often necessary to manually create new ones.
Reasons might be if a different naming system is desired (in which case Reasons might be if a different naming system is desired (in which case
see also <xref linkend="collation-copy">) or if the operating system has see also <xref linkend="collation-copy"/>) or if the operating system has
been upgraded to provide new locale definitions (in which case see been upgraded to provide new locale definitions (in which case see
also <link linkend="functions-admin-collation"><function>pg_import_system_collations()</function></link>). also <link linkend="functions-admin-collation"><function>pg_import_system_collations()</function></link>).
</para> </para>
@ -871,7 +871,7 @@ CREATE COLLATION german (provider = libc, locale = 'de_DE');
<title>Copying Collations</title> <title>Copying Collations</title>
<para> <para>
The command <xref linkend="sql-createcollation"> can also be used to The command <xref linkend="sql-createcollation"/> can also be used to
create a new collation from an existing collation, which can be useful to create a new collation from an existing collation, which can be useful to
be able to use operating-system-independent collation names in be able to use operating-system-independent collation names in
applications, create compatibility names, or use an ICU-provided collation applications, create compatibility names, or use an ICU-provided collation
@ -924,7 +924,7 @@ CREATE COLLATION french FROM "fr-x-icu";
<title>Supported Character Sets</title> <title>Supported Character Sets</title>
<para> <para>
<xref linkend="charset-table"> shows the character sets available <xref linkend="charset-table"/> shows the character sets available
for use in <productname>PostgreSQL</productname>. for use in <productname>PostgreSQL</productname>.
</para> </para>
@ -1392,7 +1392,7 @@ CREATE DATABASE korean WITH ENCODING 'EUC_KR' LC_COLLATE='ko_KR.euckr' LC_CTYPE=
database. When copying any other database, the encoding and locale database. When copying any other database, the encoding and locale
settings cannot be changed from those of the source database, because settings cannot be changed from those of the source database, because
that might result in corrupt data. For more information see that might result in corrupt data. For more information see
<xref linkend="manage-ag-templatedbs">. <xref linkend="manage-ag-templatedbs"/>.
</para> </para>
<para> <para>
@ -1449,7 +1449,7 @@ $ <userinput>psql -l</userinput>
character set combinations. The conversion information is stored in the character set combinations. The conversion information is stored in the
<literal>pg_conversion</literal> system catalog. <productname>PostgreSQL</productname> <literal>pg_conversion</literal> system catalog. <productname>PostgreSQL</productname>
comes with some predefined conversions, as shown in <xref comes with some predefined conversions, as shown in <xref
linkend="multibyte-translation-table">. You can create a new linkend="multibyte-translation-table"/>. You can create a new
conversion using the SQL command <command>CREATE CONVERSION</command>. conversion using the SQL command <command>CREATE CONVERSION</command>.
</para> </para>
@ -1763,7 +1763,7 @@ $ <userinput>psql -l</userinput>
<listitem> <listitem>
<para> <para>
<application>libpq</application> (<xref linkend="libpq-control">) has functions to control the client encoding. <application>libpq</application> (<xref linkend="libpq-control"/>) has functions to control the client encoding.
</para> </para>
</listitem> </listitem>
@ -1812,7 +1812,7 @@ RESET client_encoding;
<listitem> <listitem>
<para> <para>
Using the configuration variable <xref Using the configuration variable <xref
linkend="guc-client-encoding">. If the linkend="guc-client-encoding"/>. If the
<varname>client_encoding</varname> variable is set, that client <varname>client_encoding</varname> variable is set, that client
encoding is automatically selected when a connection to the encoding is automatically selected when a connection to the
server is made. (This can subsequently be overridden using any server is made. (This can subsequently be overridden using any

88
doc/src/sgml/client-auth.sgml
View File

@ -13,13 +13,13 @@
wants to connect as, much the same way one logs into a Unix computer wants to connect as, much the same way one logs into a Unix computer
as a particular user. Within the SQL environment the active database as a particular user. Within the SQL environment the active database
user name determines access privileges to database objects &mdash; see user name determines access privileges to database objects &mdash; see
<xref linkend="user-manag"> for more information. Therefore, it is <xref linkend="user-manag"/> for more information. Therefore, it is
essential to restrict which database users can connect. essential to restrict which database users can connect.
</para> </para>
<note> <note>
<para> <para>
As explained in <xref linkend="user-manag">, As explained in <xref linkend="user-manag"/>,
<productname>PostgreSQL</productname> actually does privilege <productname>PostgreSQL</productname> actually does privilege
management in terms of <quote>roles</quote>. In this chapter, we management in terms of <quote>roles</quote>. In this chapter, we
consistently use <firstterm>database user</firstterm> to mean <quote>role with the consistently use <firstterm>database user</firstterm> to mean <quote>role with the
@ -70,7 +70,7 @@
<filename>pg_hba.conf</filename> file is installed when the data <filename>pg_hba.conf</filename> file is installed when the data
directory is initialized by <command>initdb</command>. It is directory is initialized by <command>initdb</command>. It is
possible to place the authentication configuration file elsewhere, possible to place the authentication configuration file elsewhere,
however; see the <xref linkend="guc-hba-file"> configuration parameter. however; see the <xref linkend="guc-hba-file"/> configuration parameter.
</para> </para>
<para> <para>
@ -136,7 +136,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<para> <para>
Remote TCP/IP connections will not be possible unless Remote TCP/IP connections will not be possible unless
the server is started with an appropriate value for the the server is started with an appropriate value for the
<xref linkend="guc-listen-addresses"> configuration parameter, <xref linkend="guc-listen-addresses"/> configuration parameter,
since the default behavior is to listen for TCP/IP connections since the default behavior is to listen for TCP/IP connections
only on the local loopback address <literal>localhost</literal>. only on the local loopback address <literal>localhost</literal>.
</para> </para>
@ -157,8 +157,8 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
To make use of this option the server must be built with To make use of this option the server must be built with
<acronym>SSL</acronym> support. Furthermore, <acronym>SSL</acronym> support. Furthermore,
<acronym>SSL</acronym> must be enabled <acronym>SSL</acronym> must be enabled
by setting the <xref linkend="guc-ssl"> configuration parameter (see by setting the <xref linkend="guc-ssl"/> configuration parameter (see
<xref linkend="ssl-tcp"> for more information). <xref linkend="ssl-tcp"/> for more information).
Otherwise, the <literal>hostssl</literal> record is ignored except for Otherwise, the <literal>hostssl</literal> record is ignored except for
logging a warning that it cannot match any connections. logging a warning that it cannot match any connections.
</para> </para>
@ -381,7 +381,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<para> <para>
Specifies the authentication method to use when a connection matches Specifies the authentication method to use when a connection matches
this record. The possible choices are summarized here; details this record. The possible choices are summarized here; details
are in <xref linkend="auth-methods">. are in <xref linkend="auth-methods"/>.
<variablelist> <variablelist>
<varlistentry> <varlistentry>
@ -393,7 +393,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<productname>PostgreSQL</productname> database server to login as <productname>PostgreSQL</productname> database server to login as
any <productname>PostgreSQL</productname> user they wish, any <productname>PostgreSQL</productname> user they wish,
without the need for a password or any other authentication. See <xref without the need for a password or any other authentication. See <xref
linkend="auth-trust"> for details. linkend="auth-trust"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -416,7 +416,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<listitem> <listitem>
<para> <para>
Perform SCRAM-SHA-256 authentication to verify the user's Perform SCRAM-SHA-256 authentication to verify the user's
password. See <xref linkend="auth-password"> for details. password. See <xref linkend="auth-password"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -426,7 +426,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<listitem> <listitem>
<para> <para>
Perform SCRAM-SHA-256 or MD5 authentication to verify the Perform SCRAM-SHA-256 or MD5 authentication to verify the
user's password. See <xref linkend="auth-password"> user's password. See <xref linkend="auth-password"/>
for details. for details.
</para> </para>
</listitem> </listitem>
@ -440,7 +440,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
authentication. authentication.
Since the password is sent in clear text over the Since the password is sent in clear text over the
network, this should not be used on untrusted networks. network, this should not be used on untrusted networks.
See <xref linkend="auth-password"> for details. See <xref linkend="auth-password"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -451,7 +451,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<para> <para>
Use GSSAPI to authenticate the user. This is only Use GSSAPI to authenticate the user. This is only
available for TCP/IP connections. See <xref available for TCP/IP connections. See <xref
linkend="gssapi-auth"> for details. linkend="gssapi-auth"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -462,7 +462,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<para> <para>
Use SSPI to authenticate the user. This is only Use SSPI to authenticate the user. This is only
available on Windows. See <xref available on Windows. See <xref
linkend="sspi-auth"> for details. linkend="sspi-auth"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -477,7 +477,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
Ident authentication can only be used on TCP/IP Ident authentication can only be used on TCP/IP
connections. When specified for local connections, peer connections. When specified for local connections, peer
authentication will be used instead. authentication will be used instead.
See <xref linkend="auth-ident"> for details. See <xref linkend="auth-ident"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -489,7 +489,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
Obtain the client's operating system user name from the operating Obtain the client's operating system user name from the operating
system and check if it matches the requested database user name. system and check if it matches the requested database user name.
This is only available for local connections. This is only available for local connections.
See <xref linkend="auth-peer"> for details. See <xref linkend="auth-peer"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -499,7 +499,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<listitem> <listitem>
<para> <para>
Authenticate using an <acronym>LDAP</acronym> server. See <xref Authenticate using an <acronym>LDAP</acronym> server. See <xref
linkend="auth-ldap"> for details. linkend="auth-ldap"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -509,7 +509,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<listitem> <listitem>
<para> <para>
Authenticate using a RADIUS server. See <xref Authenticate using a RADIUS server. See <xref
linkend="auth-radius"> for details. linkend="auth-radius"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -519,7 +519,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<listitem> <listitem>
<para> <para>
Authenticate using SSL client certificates. See Authenticate using SSL client certificates. See
<xref linkend="auth-cert"> for details. <xref linkend="auth-cert"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -530,7 +530,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<para> <para>
Authenticate using the Pluggable Authentication Modules Authenticate using the Pluggable Authentication Modules
(PAM) service provided by the operating system. See <xref (PAM) service provided by the operating system. See <xref
linkend="auth-pam"> for details. linkend="auth-pam"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -540,7 +540,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<listitem> <listitem>
<para> <para>
Authenticate using the BSD Authentication service provided by the Authenticate using the BSD Authentication service provided by the
operating system. See <xref linkend="auth-bsd"> for details. operating system. See <xref linkend="auth-bsd"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -638,7 +638,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
<para> <para>
Some examples of <filename>pg_hba.conf</filename> entries are shown in Some examples of <filename>pg_hba.conf</filename> entries are shown in
<xref linkend="example-pg-hba.conf">. See the next section for details on the <xref linkend="example-pg-hba.conf"/>. See the next section for details on the
different authentication methods. different authentication methods.
</para> </para>
@ -763,7 +763,7 @@ local db1,db2,@demodbs all md5
<filename>pg_ident.conf</filename><indexterm><primary>pg_ident.conf</primary></indexterm> <filename>pg_ident.conf</filename><indexterm><primary>pg_ident.conf</primary></indexterm>
and is stored in the and is stored in the
cluster's data directory. (It is possible to place the map file cluster's data directory. (It is possible to place the map file
elsewhere, however; see the <xref linkend="guc-ident-file"> elsewhere, however; see the <xref linkend="guc-ident-file"/>
configuration parameter.) configuration parameter.)
The ident map file contains lines of the general form: The ident map file contains lines of the general form:
<synopsis> <synopsis>
@ -790,7 +790,7 @@ local db1,db2,@demodbs all md5
<para> <para>
If the <replaceable>system-username</replaceable> field starts with a slash (<literal>/</literal>), If the <replaceable>system-username</replaceable> field starts with a slash (<literal>/</literal>),
the remainder of the field is treated as a regular expression. the remainder of the field is treated as a regular expression.
(See <xref linkend="posix-syntax-details"> for details of (See <xref linkend="posix-syntax-details"/> for details of
<productname>PostgreSQL</productname>'s regular expression syntax.) The regular <productname>PostgreSQL</productname>'s regular expression syntax.) The regular
expression can include a single capture, or parenthesized subexpression, expression can include a single capture, or parenthesized subexpression,
which can then be referenced in the <replaceable>database-username</replaceable> which can then be referenced in the <replaceable>database-username</replaceable>
@ -828,8 +828,8 @@ mymap /^(.*)@otherdomain\.com$ guest
<para> <para>
A <filename>pg_ident.conf</filename> file that could be used in A <filename>pg_ident.conf</filename> file that could be used in
conjunction with the <filename>pg_hba.conf</filename> file in <xref conjunction with the <filename>pg_hba.conf</filename> file in <xref
linkend="example-pg-hba.conf"> is shown in <xref linkend="example-pg-hba.conf"/> is shown in <xref
linkend="example-pg-ident.conf">. In this example, anyone linkend="example-pg-ident.conf"/>. In this example, anyone
logged in to a machine on the 192.168 network that does not have the logged in to a machine on the 192.168 network that does not have the
operating system user name <literal>bryanh</literal>, <literal>ann</literal>, or operating system user name <literal>bryanh</literal>, <literal>ann</literal>, or
<literal>robert</literal> would not be granted access. Unix user <literal>robert</literal> would not be granted access. Unix user
@ -885,7 +885,7 @@ omicron bryanh guest1
Unix-domain socket file using file-system permissions. To do this, set the Unix-domain socket file using file-system permissions. To do this, set the
<varname>unix_socket_permissions</varname> (and possibly <varname>unix_socket_permissions</varname> (and possibly
<varname>unix_socket_group</varname>) configuration parameters as <varname>unix_socket_group</varname>) configuration parameters as
described in <xref linkend="runtime-config-connection">. Or you described in <xref linkend="runtime-config-connection"/>. Or you
could set the <varname>unix_socket_directories</varname> could set the <varname>unix_socket_directories</varname>
configuration parameter to place the socket file in a suitably configuration parameter to place the socket file in a suitably
restricted directory. restricted directory.
@ -965,7 +965,7 @@ omicron bryanh guest1
<para> <para>
The <literal>md5</literal> method cannot be used with The <literal>md5</literal> method cannot be used with
the <xref linkend="guc-db-user-namespace"> feature. the <xref linkend="guc-db-user-namespace"/> feature.
</para> </para>
<para> <para>
@ -998,8 +998,8 @@ omicron bryanh guest1
separate from operating system user passwords. The password for separate from operating system user passwords. The password for
each database user is stored in the <literal>pg_authid</literal> system each database user is stored in the <literal>pg_authid</literal> system
catalog. Passwords can be managed with the SQL commands catalog. Passwords can be managed with the SQL commands
<xref linkend="sql-createrole"> and <xref linkend="sql-createrole"/> and
<xref linkend="sql-alterrole">, <xref linkend="sql-alterrole"/>,
e.g., <userinput>CREATE ROLE foo WITH LOGIN PASSWORD 'secret'</userinput>, e.g., <userinput>CREATE ROLE foo WITH LOGIN PASSWORD 'secret'</userinput>,
or the <application>psql</application> or the <application>psql</application>
command <literal>\password</literal>. command <literal>\password</literal>.
@ -1011,7 +1011,7 @@ omicron bryanh guest1
The availability of the different password-based authentication methods The availability of the different password-based authentication methods
depends on how a user's password on the server is encrypted (or hashed, depends on how a user's password on the server is encrypted (or hashed,
more accurately). This is controlled by the configuration more accurately). This is controlled by the configuration
parameter <xref linkend="guc-password-encryption"> at the time the parameter <xref linkend="guc-password-encryption"/> at the time the
password is set. If a password was encrypted using password is set. If a password was encrypted using
the <literal>scram-sha-256</literal> setting, then it can be used for the the <literal>scram-sha-256</literal> setting, then it can be used for the
authentication methods <literal>scram-sha-256</literal> authentication methods <literal>scram-sha-256</literal>
@ -1061,7 +1061,7 @@ omicron bryanh guest1
<para> <para>
GSSAPI support has to be enabled when <productname>PostgreSQL</productname> is built; GSSAPI support has to be enabled when <productname>PostgreSQL</productname> is built;
see <xref linkend="installation"> for more information. see <xref linkend="installation"/> for more information.
</para> </para>
<para> <para>
@ -1072,7 +1072,7 @@ omicron bryanh guest1
The PostgreSQL server will accept any principal that is included in the keytab used by The PostgreSQL server will accept any principal that is included in the keytab used by
the server, but care needs to be taken to specify the correct principal details when the server, but care needs to be taken to specify the correct principal details when
making the connection from the client using the <literal>krbsrvname</literal> connection parameter. (See making the connection from the client using the <literal>krbsrvname</literal> connection parameter. (See
also <xref linkend="libpq-paramkeywords">.) The installation default can be also <xref linkend="libpq-paramkeywords"/>.) The installation default can be
changed from the default <literal>postgres</literal> at build time using changed from the default <literal>postgres</literal> at build time using
<literal>./configure --with-krb-srvnam=</literal><replaceable>whatever</replaceable>. <literal>./configure --with-krb-srvnam=</literal><replaceable>whatever</replaceable>.
In most environments, In most environments,
@ -1112,9 +1112,9 @@ omicron bryanh guest1
<para> <para>
Make sure that your server keytab file is readable (and preferably Make sure that your server keytab file is readable (and preferably
only readable, not writable) by the <productname>PostgreSQL</productname> only readable, not writable) by the <productname>PostgreSQL</productname>
server account. (See also <xref linkend="postgres-user">.) The location server account. (See also <xref linkend="postgres-user"/>.) The location
of the key file is specified by the <xref of the key file is specified by the <xref
linkend="guc-krb-server-keyfile"> configuration linkend="guc-krb-server-keyfile"/> configuration
parameter. The default is parameter. The default is
<filename>/usr/local/pgsql/etc/krb5.keytab</filename> (or whatever <filename>/usr/local/pgsql/etc/krb5.keytab</filename> (or whatever
directory was specified as <varname>sysconfdir</varname> at build time). directory was specified as <varname>sysconfdir</varname> at build time).
@ -1138,7 +1138,7 @@ omicron bryanh guest1
database user name <literal>fred</literal>, principal database user name <literal>fred</literal>, principal
<literal>fred@EXAMPLE.COM</literal> would be able to connect. To also allow <literal>fred@EXAMPLE.COM</literal> would be able to connect. To also allow
principal <literal>fred/users.example.com@EXAMPLE.COM</literal>, use a user name principal <literal>fred/users.example.com@EXAMPLE.COM</literal>, use a user name
map, as described in <xref linkend="auth-username-maps">. map, as described in <xref linkend="auth-username-maps"/>.
</para> </para>
<para> <para>
@ -1150,7 +1150,7 @@ omicron bryanh guest1
<para> <para>
If set to 0, the realm name from the authenticated user principal is If set to 0, the realm name from the authenticated user principal is
stripped off before being passed through the user name mapping stripped off before being passed through the user name mapping
(<xref linkend="auth-username-maps">). This is discouraged and is (<xref linkend="auth-username-maps"/>). This is discouraged and is
primarily available for backwards compatibility, as it is not secure primarily available for backwards compatibility, as it is not secure
in multi-realm environments unless <literal>krb_realm</literal> is in multi-realm environments unless <literal>krb_realm</literal> is
also used. It is recommended to also used. It is recommended to
@ -1166,7 +1166,7 @@ omicron bryanh guest1
<listitem> <listitem>
<para> <para>
Allows for mapping between system and database user names. See Allows for mapping between system and database user names. See
<xref linkend="auth-username-maps"> for details. For a GSSAPI/Kerberos <xref linkend="auth-username-maps"/> for details. For a GSSAPI/Kerberos
principal, such as <literal>username@EXAMPLE.COM</literal> (or, less principal, such as <literal>username@EXAMPLE.COM</literal> (or, less
commonly, <literal>username/hostbased@EXAMPLE.COM</literal>), the commonly, <literal>username/hostbased@EXAMPLE.COM</literal>), the
user name used for mapping is user name used for mapping is
@ -1217,7 +1217,7 @@ omicron bryanh guest1
<para> <para>
When using <productname>Kerberos</productname> authentication, When using <productname>Kerberos</productname> authentication,
<productname>SSPI</productname> works the same way <productname>SSPI</productname> works the same way
<productname>GSSAPI</productname> does; see <xref linkend="gssapi-auth"> <productname>GSSAPI</productname> does; see <xref linkend="gssapi-auth"/>
for details. for details.
</para> </para>
@ -1231,7 +1231,7 @@ omicron bryanh guest1
<para> <para>
If set to 0, the realm name from the authenticated user principal is If set to 0, the realm name from the authenticated user principal is
stripped off before being passed through the user name mapping stripped off before being passed through the user name mapping
(<xref linkend="auth-username-maps">). This is discouraged and is (<xref linkend="auth-username-maps"/>). This is discouraged and is
primarily available for backwards compatibility, as it is not secure primarily available for backwards compatibility, as it is not secure
in multi-realm environments unless <literal>krb_realm</literal> is in multi-realm environments unless <literal>krb_realm</literal> is
also used. It is recommended to also used. It is recommended to
@ -1284,7 +1284,7 @@ omicron bryanh guest1
<listitem> <listitem>
<para> <para>
Allows for mapping between system and database user names. See Allows for mapping between system and database user names. See
<xref linkend="auth-username-maps"> for details. For a SSPI/Kerberos <xref linkend="auth-username-maps"/> for details. For a SSPI/Kerberos
principal, such as <literal>username@EXAMPLE.COM</literal> (or, less principal, such as <literal>username@EXAMPLE.COM</literal> (or, less
commonly, <literal>username/hostbased@EXAMPLE.COM</literal>), the commonly, <literal>username/hostbased@EXAMPLE.COM</literal>), the
user name used for mapping is user name used for mapping is
@ -1329,7 +1329,7 @@ omicron bryanh guest1
<note> <note>
<para> <para>
When ident is specified for a local (non-TCP/IP) connection, When ident is specified for a local (non-TCP/IP) connection,
peer authentication (see <xref linkend="auth-peer">) will be peer authentication (see <xref linkend="auth-peer"/>) will be
used instead. used instead.
</para> </para>
</note> </note>
@ -1342,7 +1342,7 @@ omicron bryanh guest1
<listitem> <listitem>
<para> <para>
Allows for mapping between system and database user names. See Allows for mapping between system and database user names. See
<xref linkend="auth-username-maps"> for details. <xref linkend="auth-username-maps"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1415,7 +1415,7 @@ omicron bryanh guest1
<listitem> <listitem>
<para> <para>
Allows for mapping between system and database user names. See Allows for mapping between system and database user names. See
<xref linkend="auth-username-maps"> for details. <xref linkend="auth-username-maps"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1828,7 +1828,7 @@ host ... ldap ldapserver=ldap.example.net ldapbasedn="dc=example, dc=net" ldapse
<listitem> <listitem>
<para> <para>
Allows for mapping between system and database user names. See Allows for mapping between system and database user names. See
<xref linkend="auth-username-maps"> for details. <xref linkend="auth-username-maps"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>

362
doc/src/sgml/config.sgml
View File

File diff suppressed because it is too large Load Diff

18
doc/src/sgml/contrib.sgml
View File

@ -16,14 +16,14 @@
<para> <para>
This appendix covers extensions and other server plug-in modules found in This appendix covers extensions and other server plug-in modules found in
<literal>contrib</literal>. <xref linkend="contrib-prog"> covers utility <literal>contrib</literal>. <xref linkend="contrib-prog"/> covers utility
programs. programs.
</para> </para>
<para> <para>
When building from the source distribution, these components are not built When building from the source distribution, these components are not built
automatically, unless you build the "world" target automatically, unless you build the "world" target
(see <xref linkend="build">). (see <xref linkend="build"/>).
You can build and install all of them by running: You can build and install all of them by running:
<screen> <screen>
<userinput>make</userinput> <userinput>make</userinput>
@ -55,7 +55,7 @@
To make use of one of these modules, after you have installed the code To make use of one of these modules, after you have installed the code
you need to register the new SQL objects in the database system. you need to register the new SQL objects in the database system.
In <productname>PostgreSQL</productname> 9.1 and later, this is done by executing In <productname>PostgreSQL</productname> 9.1 and later, this is done by executing
a <xref linkend="sql-createextension"> command. In a fresh database, a <xref linkend="sql-createextension"/> command. In a fresh database,
you can simply do you can simply do
<programlisting> <programlisting>
@ -89,16 +89,16 @@ CREATE EXTENSION <replaceable>module_name</replaceable> FROM unpackaged;
This will update the pre-9.1 objects of the module into a proper This will update the pre-9.1 objects of the module into a proper
<firstterm>extension</firstterm> object. Future updates to the module will be <firstterm>extension</firstterm> object. Future updates to the module will be
managed by <xref linkend="sql-alterextension">. managed by <xref linkend="sql-alterextension"/>.
For more information about extension updates, see For more information about extension updates, see
<xref linkend="extend-extensions">. <xref linkend="extend-extensions"/>.
</para> </para>
<para> <para>
Note, however, that some of these modules are not <quote>extensions</quote> Note, however, that some of these modules are not <quote>extensions</quote>
in this sense, but are loaded into the server in some other way, for instance in this sense, but are loaded into the server in some other way, for instance
by way of by way of
<xref linkend="guc-shared-preload-libraries">. See the documentation of each <xref linkend="guc-shared-preload-libraries"/>. See the documentation of each
module for details. module for details.
</para> </para>
@ -163,7 +163,7 @@ pages.
<para> <para>
This appendix and the previous one contain information regarding the modules that This appendix and the previous one contain information regarding the modules that
can be found in the <literal>contrib</literal> directory of the can be found in the <literal>contrib</literal> directory of the
<productname>PostgreSQL</productname> distribution. See <xref linkend="contrib"> for <productname>PostgreSQL</productname> distribution. See <xref linkend="contrib"/> for
more information about the <literal>contrib</literal> section in general and more information about the <literal>contrib</literal> section in general and
server extensions and plug-ins found in <literal>contrib</literal> server extensions and plug-ins found in <literal>contrib</literal>
specifically. specifically.
@ -184,7 +184,7 @@ pages.
This section covers <productname>PostgreSQL</productname> client This section covers <productname>PostgreSQL</productname> client
applications in <literal>contrib</literal>. They can be run from anywhere, applications in <literal>contrib</literal>. They can be run from anywhere,
independent of where the database server resides. See independent of where the database server resides. See
also <xref linkend="reference-client"> for information about client also <xref linkend="reference-client"/> for information about client
applications that part of the core <productname>PostgreSQL</productname> applications that part of the core <productname>PostgreSQL</productname>
distribution. distribution.
</para> </para>
@ -200,7 +200,7 @@ pages.
This section covers <productname>PostgreSQL</productname> server-related This section covers <productname>PostgreSQL</productname> server-related
applications in <literal>contrib</literal>. They are typically run on the applications in <literal>contrib</literal>. They are typically run on the
host where the database server resides. See also <xref host where the database server resides. See also <xref
linkend="reference-server"> for information about server applications that linkend="reference-server"/> for information about server applications that
part of the core <productname>PostgreSQL</productname> distribution. part of the core <productname>PostgreSQL</productname> distribution.
</para> </para>

6
doc/src/sgml/cube.sgml
View File

@ -16,7 +16,7 @@
<title>Syntax</title> <title>Syntax</title>
<para> <para>
<xref linkend="cube-repr-table"> shows the valid external <xref linkend="cube-repr-table"/> shows the valid external
representations for the <type>cube</type> representations for the <type>cube</type>
type. <replaceable>x</replaceable>, <replaceable>y</replaceable>, etc. denote type. <replaceable>x</replaceable>, <replaceable>y</replaceable>, etc. denote
floating-point numbers. floating-point numbers.
@ -106,7 +106,7 @@
<title>Usage</title> <title>Usage</title>
<para> <para>
<xref linkend="cube-operators-table"> shows the operators provided for <xref linkend="cube-operators-table"/> shows the operators provided for
type <type>cube</type>. type <type>cube</type>.
</para> </para>
@ -268,7 +268,7 @@ SELECT c FROM test ORDER BY c ~&gt; 3 DESC LIMIT 5;
</para> </para>
<para> <para>
<xref linkend="cube-functions-table"> shows the available functions. <xref linkend="cube-functions-table"/> shows the available functions.
</para> </para>
<table id="cube-functions-table"> <table id="cube-functions-table">

2
doc/src/sgml/custom-scan.sgml
View File

@ -123,7 +123,7 @@ Plan *(*PlanCustomPath) (PlannerInfo *root,
</programlisting> </programlisting>
Convert a custom path to a finished plan. The return value will generally Convert a custom path to a finished plan. The return value will generally
be a <literal>CustomScan</literal> object, which the callback must allocate and be a <literal>CustomScan</literal> object, which the callback must allocate and
initialize. See <xref linkend="custom-scan-plan"> for more details. initialize. See <xref linkend="custom-scan-plan"/> for more details.
</para> </para>
</sect2> </sect2>
</sect1> </sect1>

176
doc/src/sgml/datatype.sgml
View File

@ -16,11 +16,11 @@
<productname>PostgreSQL</productname> has a rich set of native data <productname>PostgreSQL</productname> has a rich set of native data
types available to users. Users can add new types to types available to users. Users can add new types to
<productname>PostgreSQL</productname> using the <xref <productname>PostgreSQL</productname> using the <xref
linkend="sql-createtype"> command. linkend="sql-createtype"/> command.
</para> </para>
<para> <para>
<xref linkend="datatype-table"> shows all the built-in general-purpose data <xref linkend="datatype-table"/> shows all the built-in general-purpose data
types. Most of the alternative names listed in the types. Most of the alternative names listed in the
<quote>Aliases</quote> column are the names used internally by <quote>Aliases</quote> column are the names used internally by
<productname>PostgreSQL</productname> for historical reasons. In <productname>PostgreSQL</productname> for historical reasons. In
@ -336,7 +336,7 @@
<para> <para>
Numeric types consist of two-, four-, and eight-byte integers, Numeric types consist of two-, four-, and eight-byte integers,
four- and eight-byte floating-point numbers, and selectable-precision four- and eight-byte floating-point numbers, and selectable-precision
decimals. <xref linkend="datatype-numeric-table"> lists the decimals. <xref linkend="datatype-numeric-table"/> lists the
available types. available types.
</para> </para>
@ -424,9 +424,9 @@
<para> <para>
The syntax of constants for the numeric types is described in The syntax of constants for the numeric types is described in
<xref linkend="sql-syntax-constants">. The numeric types have a <xref linkend="sql-syntax-constants"/>. The numeric types have a
full set of corresponding arithmetic operators and full set of corresponding arithmetic operators and
functions. Refer to <xref linkend="functions"> for more functions. Refer to <xref linkend="functions"/> for more
information. The following sections describe the types in detail. information. The following sections describe the types in detail.
</para> </para>
@ -559,7 +559,7 @@ NUMERIC
The maximum allowed precision when explicitly specified in the The maximum allowed precision when explicitly specified in the
type declaration is 1000; <type>NUMERIC</type> without a specified type declaration is 1000; <type>NUMERIC</type> without a specified
precision is subject to the limits described in <xref precision is subject to the limits described in <xref
linkend="datatype-numeric-table">. linkend="datatype-numeric-table"/>.
</para> </para>
</note> </note>
@ -728,7 +728,7 @@ FROM generate_series(-3.5, 3.5, 1) as x;
<note> <note>
<para> <para>
The <xref linkend="guc-extra-float-digits"> setting controls the The <xref linkend="guc-extra-float-digits"/> setting controls the
number of extra significant digits included when a floating point number of extra significant digits included when a floating point
value is converted to text for output. With the default value of value is converted to text for output. With the default value of
<literal>0</literal>, the output is the same on every platform <literal>0</literal>, the output is the same on every platform
@ -841,7 +841,7 @@ FROM generate_series(-3.5, 3.5, 1) as x;
<para> <para>
This section describes a PostgreSQL-specific way to create an This section describes a PostgreSQL-specific way to create an
autoincrementing column. Another way is to use the SQL-standard autoincrementing column. Another way is to use the SQL-standard
identity column feature, described at <xref linkend="sql-createtable">. identity column feature, described at <xref linkend="sql-createtable"/>.
</para> </para>
</note> </note>
@ -888,7 +888,7 @@ ALTER SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceab
from the sequence is still "used up" even if a row containing that from the sequence is still "used up" even if a row containing that
value is never successfully inserted into the table column. This value is never successfully inserted into the table column. This
may happen, for example, if the inserting transaction rolls back. may happen, for example, if the inserting transaction rolls back.
See <literal>nextval()</literal> in <xref linkend="functions-sequence"> See <literal>nextval()</literal> in <xref linkend="functions-sequence"/>
for details. for details.
</para> </para>
</note> </note>
@ -929,8 +929,8 @@ ALTER SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceab
<para> <para>
The <type>money</type> type stores a currency amount with a fixed The <type>money</type> type stores a currency amount with a fixed
fractional precision; see <xref fractional precision; see <xref
linkend="datatype-money-table">. The fractional precision is linkend="datatype-money-table"/>. The fractional precision is
determined by the database's <xref linkend="guc-lc-monetary"> setting. determined by the database's <xref linkend="guc-lc-monetary"/> setting.
The range shown in the table assumes there are two fractional digits. The range shown in the table assumes there are two fractional digits.
Input is accepted in a variety of formats, including integer and Input is accepted in a variety of formats, including integer and
floating-point literals, as well as typical floating-point literals, as well as typical
@ -1063,7 +1063,7 @@ SELECT '52093.89'::money::numeric::float8;
</table> </table>
<para> <para>
<xref linkend="datatype-character-table"> shows the <xref linkend="datatype-character-table"/> shows the
general-purpose character types available in general-purpose character types available in
<productname>PostgreSQL</productname>. <productname>PostgreSQL</productname>.
</para> </para>
@ -1166,12 +1166,12 @@ SELECT '52093.89'::money::numeric::float8;
</tip> </tip>
<para> <para>
Refer to <xref linkend="sql-syntax-strings"> for information about Refer to <xref linkend="sql-syntax-strings"/> for information about
the syntax of string literals, and to <xref linkend="functions"> the syntax of string literals, and to <xref linkend="functions"/>
for information about available operators and functions. The for information about available operators and functions. The
database character set determines the character set used to store database character set determines the character set used to store
textual values; for more information on character set support, textual values; for more information on character set support,
refer to <xref linkend="multibyte">. refer to <xref linkend="multibyte"/>.
</para> </para>
<example> <example>
@ -1180,7 +1180,7 @@ SELECT '52093.89'::money::numeric::float8;
<programlisting> <programlisting>
CREATE TABLE test1 (a character(4)); CREATE TABLE test1 (a character(4));
INSERT INTO test1 VALUES ('ok'); INSERT INTO test1 VALUES ('ok');
SELECT a, char_length(a) FROM test1; -- <co id="co.datatype-char"> SELECT a, char_length(a) FROM test1; -- <co id="co.datatype-char"/>
<computeroutput> <computeroutput>
a | char_length a | char_length
------+------------- ------+-------------
@ -1206,7 +1206,7 @@ SELECT b, char_length(b) FROM test2;
<callout arearefs="co.datatype-char"> <callout arearefs="co.datatype-char">
<para> <para>
The <function>char_length</function> function is discussed in The <function>char_length</function> function is discussed in
<xref linkend="functions-string">. <xref linkend="functions-string"/>.
</para> </para>
</callout> </callout>
</calloutlist> </calloutlist>
@ -1215,7 +1215,7 @@ SELECT b, char_length(b) FROM test2;
<para> <para>
There are two other fixed-length character types in There are two other fixed-length character types in
<productname>PostgreSQL</productname>, shown in <xref <productname>PostgreSQL</productname>, shown in <xref
linkend="datatype-character-special-table">. The <type>name</type> linkend="datatype-character-special-table"/>. The <type>name</type>
type exists <emphasis>only</emphasis> for the storage of identifiers type exists <emphasis>only</emphasis> for the storage of identifiers
in the internal system catalogs and is not intended for use by the general user. Its in the internal system catalogs and is not intended for use by the general user. Its
length is currently defined as 64 bytes (63 usable characters plus length is currently defined as 64 bytes (63 usable characters plus
@ -1269,7 +1269,7 @@ SELECT b, char_length(b) FROM test2;
<para> <para>
The <type>bytea</type> data type allows storage of binary strings; The <type>bytea</type> data type allows storage of binary strings;
see <xref linkend="datatype-binary-table">. see <xref linkend="datatype-binary-table"/>.
</para> </para>
<table id="datatype-binary-table"> <table id="datatype-binary-table">
@ -1313,7 +1313,7 @@ SELECT b, char_length(b) FROM test2;
input and output: <productname>PostgreSQL</productname>'s historical input and output: <productname>PostgreSQL</productname>'s historical
<quote>escape</quote> format, and <quote>hex</quote> format. Both <quote>escape</quote> format, and <quote>hex</quote> format. Both
of these are always accepted on input. The output format depends of these are always accepted on input. The output format depends
on the configuration parameter <xref linkend="guc-bytea-output">; on the configuration parameter <xref linkend="guc-bytea-output"/>;
the default is hex. (Note that the hex format was introduced in the default is hex. (Note that the hex format was introduced in
<productname>PostgreSQL</productname> 9.0; earlier versions and some <productname>PostgreSQL</productname> 9.0; earlier versions and some
tools don't understand it.) tools don't understand it.)
@ -1384,7 +1384,7 @@ SELECT E'\\xDEADBEEF';
literal using escape string syntax). literal using escape string syntax).
Backslash itself (octet value 92) can alternatively be represented by Backslash itself (octet value 92) can alternatively be represented by
double backslashes. double backslashes.
<xref linkend="datatype-binary-sqlesc"> <xref linkend="datatype-binary-sqlesc"/>
shows the characters that must be escaped, and gives the alternative shows the characters that must be escaped, and gives the alternative
escape sequences where applicable. escape sequences where applicable.
</para> </para>
@ -1443,14 +1443,14 @@ SELECT E'\\xDEADBEEF';
The requirement to escape <emphasis>non-printable</emphasis> octets The requirement to escape <emphasis>non-printable</emphasis> octets
varies depending on locale settings. In some instances you can get away varies depending on locale settings. In some instances you can get away
with leaving them unescaped. Note that the result in each of the examples with leaving them unescaped. Note that the result in each of the examples
in <xref linkend="datatype-binary-sqlesc"> was exactly one octet in in <xref linkend="datatype-binary-sqlesc"/> was exactly one octet in
length, even though the output representation is sometimes length, even though the output representation is sometimes
more than one character. more than one character.
</para> </para>
<para> <para>
The reason multiple backslashes are required, as shown The reason multiple backslashes are required, as shown
in <xref linkend="datatype-binary-sqlesc">, is that an input in <xref linkend="datatype-binary-sqlesc"/>, is that an input
string written as a string literal must pass through two parse string written as a string literal must pass through two parse
phases in the <productname>PostgreSQL</productname> server. phases in the <productname>PostgreSQL</productname> server.
The first backslash of each pair is interpreted as an escape The first backslash of each pair is interpreted as an escape
@ -1467,7 +1467,7 @@ SELECT E'\\xDEADBEEF';
to a single octet with a decimal value of 1. Note that the to a single octet with a decimal value of 1. Note that the
single-quote character is not treated specially by <type>bytea</type>, single-quote character is not treated specially by <type>bytea</type>,
so it follows the normal rules for string literals. (See also so it follows the normal rules for string literals. (See also
<xref linkend="sql-syntax-strings">.) <xref linkend="sql-syntax-strings"/>.)
</para> </para>
<para> <para>
@ -1477,7 +1477,7 @@ SELECT E'\\xDEADBEEF';
Most <quote>printable</quote> octets are represented by their standard Most <quote>printable</quote> octets are represented by their standard
representation in the client character set. The octet with decimal representation in the client character set. The octet with decimal
value 92 (backslash) is doubled in the output. value 92 (backslash) is doubled in the output.
Details are in <xref linkend="datatype-binary-resesc">. Details are in <xref linkend="datatype-binary-resesc"/>.
</para> </para>
<table id="datatype-binary-resesc"> <table id="datatype-binary-resesc">
@ -1571,12 +1571,12 @@ SELECT E'\\xDEADBEEF';
<para> <para>
<productname>PostgreSQL</productname> supports the full set of <productname>PostgreSQL</productname> supports the full set of
<acronym>SQL</acronym> date and time types, shown in <xref <acronym>SQL</acronym> date and time types, shown in <xref
linkend="datatype-datetime-table">. The operations available linkend="datatype-datetime-table"/>. The operations available
on these data types are described in on these data types are described in
<xref linkend="functions-datetime">. <xref linkend="functions-datetime"/>.
Dates are counted according to the Gregorian calendar, even in Dates are counted according to the Gregorian calendar, even in
years before that calendar was introduced (see <xref years before that calendar was introduced (see <xref
linkend="datetime-units-history"> for more information). linkend="datetime-units-history"/> for more information).
</para> </para>
<table id="datatype-datetime-table"> <table id="datatype-datetime-table">
@ -1716,7 +1716,7 @@ MINUTE TO SECOND
traditional <productname>POSTGRES</productname>, and others. traditional <productname>POSTGRES</productname>, and others.
For some formats, ordering of day, month, and year in date input is For some formats, ordering of day, month, and year in date input is
ambiguous and there is support for specifying the expected ambiguous and there is support for specifying the expected
ordering of these fields. Set the <xref linkend="guc-datestyle"> parameter ordering of these fields. Set the <xref linkend="guc-datestyle"/> parameter
to <literal>MDY</literal> to select month-day-year interpretation, to <literal>MDY</literal> to select month-day-year interpretation,
<literal>DMY</literal> to select day-month-year interpretation, or <literal>DMY</literal> to select day-month-year interpretation, or
<literal>YMD</literal> to select year-month-day interpretation. <literal>YMD</literal> to select year-month-day interpretation.
@ -1726,7 +1726,7 @@ MINUTE TO SECOND
<productname>PostgreSQL</productname> is more flexible in <productname>PostgreSQL</productname> is more flexible in
handling date/time input than the handling date/time input than the
<acronym>SQL</acronym> standard requires. <acronym>SQL</acronym> standard requires.
See <xref linkend="datetime-appendix"> See <xref linkend="datetime-appendix"/>
for the exact parsing rules of date/time input and for the for the exact parsing rules of date/time input and for the
recognized text fields including months, days of the week, and recognized text fields including months, days of the week, and
time zones. time zones.
@ -1735,7 +1735,7 @@ MINUTE TO SECOND
<para> <para>
Remember that any date or time literal input needs to be enclosed Remember that any date or time literal input needs to be enclosed
in single quotes, like text strings. Refer to in single quotes, like text strings. Refer to
<xref linkend="sql-syntax-constants-generic"> for more <xref linkend="sql-syntax-constants-generic"/> for more
information. information.
<acronym>SQL</acronym> requires the following syntax <acronym>SQL</acronym> requires the following syntax
<synopsis> <synopsis>
@ -1759,7 +1759,7 @@ MINUTE TO SECOND
</indexterm> </indexterm>
<para> <para>
<xref linkend="datatype-datetime-date-table"> shows some possible <xref linkend="datatype-datetime-date-table"/> shows some possible
inputs for the <type>date</type> type. inputs for the <type>date</type> type.
</para> </para>
@ -1872,8 +1872,8 @@ MINUTE TO SECOND
<para> <para>
Valid input for these types consists of a time of day followed Valid input for these types consists of a time of day followed
by an optional time zone. (See <xref by an optional time zone. (See <xref
linkend="datatype-datetime-time-table"> linkend="datatype-datetime-time-table"/>
and <xref linkend="datatype-timezone-table">.) If a time zone is and <xref linkend="datatype-timezone-table"/>.) If a time zone is
specified in the input for <type>time without time zone</type>, specified in the input for <type>time without time zone</type>,
it is silently ignored. You can also specify a date but it will it is silently ignored. You can also specify a date but it will
be ignored, except when you use a time zone name that involves a be ignored, except when you use a time zone name that involves a
@ -1993,7 +1993,7 @@ MINUTE TO SECOND
</table> </table>
<para> <para>
Refer to <xref linkend="datatype-timezones"> for more information on how Refer to <xref linkend="datatype-timezones"/> for more information on how
to specify time zones. to specify time zones.
</para> </para>
</sect3> </sect3>
@ -2074,7 +2074,7 @@ January 8 04:05:06 1999 PST
time zone specified is converted to UTC using the appropriate offset time zone specified is converted to UTC using the appropriate offset
for that time zone. If no time zone is stated in the input string, for that time zone. If no time zone is stated in the input string,
then it is assumed to be in the time zone indicated by the system's then it is assumed to be in the time zone indicated by the system's
<xref linkend="guc-timezone"> parameter, and is converted to UTC using the <xref linkend="guc-timezone"/> parameter, and is converted to UTC using the
offset for the <varname>timezone</varname> zone. offset for the <varname>timezone</varname> zone.
</para> </para>
@ -2084,7 +2084,7 @@ January 8 04:05:06 1999 PST
current <varname>timezone</varname> zone, and displayed as local time in that current <varname>timezone</varname> zone, and displayed as local time in that
zone. To see the time in another time zone, either change zone. To see the time in another time zone, either change
<varname>timezone</varname> or use the <literal>AT TIME ZONE</literal> construct <varname>timezone</varname> or use the <literal>AT TIME ZONE</literal> construct
(see <xref linkend="functions-datetime-zoneconvert">). (see <xref linkend="functions-datetime-zoneconvert"/>).
</para> </para>
<para> <para>
@ -2112,7 +2112,7 @@ January 8 04:05:06 1999 PST
<para> <para>
<productname>PostgreSQL</productname> supports several <productname>PostgreSQL</productname> supports several
special date/time input values for convenience, as shown in <xref special date/time input values for convenience, as shown in <xref
linkend="datatype-datetime-special-table">. The values linkend="datatype-datetime-special-table"/>. The values
<literal>infinity</literal> and <literal>-infinity</literal> <literal>infinity</literal> and <literal>-infinity</literal>
are specially represented inside the system and will be displayed are specially represented inside the system and will be displayed
unchanged; but the others are simply notational shorthands unchanged; but the others are simply notational shorthands
@ -2186,7 +2186,7 @@ January 8 04:05:06 1999 PST
<literal>CURRENT_TIMESTAMP</literal>, <literal>LOCALTIME</literal>, <literal>CURRENT_TIMESTAMP</literal>, <literal>LOCALTIME</literal>,
<literal>LOCALTIMESTAMP</literal>. The latter four accept an <literal>LOCALTIMESTAMP</literal>. The latter four accept an
optional subsecond precision specification. (See <xref optional subsecond precision specification. (See <xref
linkend="functions-datetime-current">.) Note that these are linkend="functions-datetime-current"/>.) Note that these are
SQL functions and are <emphasis>not</emphasis> recognized in data input strings. SQL functions and are <emphasis>not</emphasis> recognized in data input strings.
</para> </para>
@ -2218,7 +2218,7 @@ January 8 04:05:06 1999 PST
<acronym>SQL</acronym> standard requires the use of the ISO 8601 <acronym>SQL</acronym> standard requires the use of the ISO 8601
format. The name of the <quote>SQL</quote> output format is a format. The name of the <quote>SQL</quote> output format is a
historical accident.) <xref historical accident.) <xref
linkend="datatype-datetime-output-table"> shows examples of each linkend="datatype-datetime-output-table"/> shows examples of each
output style. The output of the <type>date</type> and output style. The output of the <type>date</type> and
<type>time</type> types is generally only the date or time part <type>time</type> types is generally only the date or time part
in accordance with the given examples. However, the in accordance with the given examples. However, the
@ -2275,9 +2275,9 @@ January 8 04:05:06 1999 PST
In the <acronym>SQL</acronym> and POSTGRES styles, day appears before In the <acronym>SQL</acronym> and POSTGRES styles, day appears before
month if DMY field ordering has been specified, otherwise month appears month if DMY field ordering has been specified, otherwise month appears
before day. before day.
(See <xref linkend="datatype-datetime-input"> (See <xref linkend="datatype-datetime-input"/>
for how this setting also affects interpretation of input values.) for how this setting also affects interpretation of input values.)
<xref linkend="datatype-datetime-output2-table"> shows examples. <xref linkend="datatype-datetime-output2-table"/> shows examples.
</para> </para>
<table id="datatype-datetime-output2-table"> <table id="datatype-datetime-output2-table">
@ -2313,7 +2313,7 @@ January 8 04:05:06 1999 PST
<para> <para>
The date/time style can be selected by the user using the The date/time style can be selected by the user using the
<command>SET datestyle</command> command, the <xref <command>SET datestyle</command> command, the <xref
linkend="guc-datestyle"> parameter in the linkend="guc-datestyle"/> parameter in the
<filename>postgresql.conf</filename> configuration file, or the <filename>postgresql.conf</filename> configuration file, or the
<envar>PGDATESTYLE</envar> environment variable on the server or <envar>PGDATESTYLE</envar> environment variable on the server or
client. client.
@ -2321,7 +2321,7 @@ January 8 04:05:06 1999 PST
<para> <para>
The formatting function <function>to_char</function> The formatting function <function>to_char</function>
(see <xref linkend="functions-formatting">) is also available as (see <xref linkend="functions-formatting"/>) is also available as
a more flexible way to format date/time output. a more flexible way to format date/time output.
</para> </para>
</sect2> </sect2>
@ -2391,7 +2391,7 @@ January 8 04:05:06 1999 PST
<para> <para>
All timezone-aware dates and times are stored internally in All timezone-aware dates and times are stored internally in
<acronym>UTC</acronym>. They are converted to local time <acronym>UTC</acronym>. They are converted to local time
in the zone specified by the <xref linkend="guc-timezone"> configuration in the zone specified by the <xref linkend="guc-timezone"/> configuration
parameter before being displayed to the client. parameter before being displayed to the client.
</para> </para>
@ -2404,7 +2404,7 @@ January 8 04:05:06 1999 PST
A full time zone name, for example <literal>America/New_York</literal>. A full time zone name, for example <literal>America/New_York</literal>.
The recognized time zone names are listed in the The recognized time zone names are listed in the
<literal>pg_timezone_names</literal> view (see <xref <literal>pg_timezone_names</literal> view (see <xref
linkend="view-pg-timezone-names">). linkend="view-pg-timezone-names"/>).
<productname>PostgreSQL</productname> uses the widely-used IANA <productname>PostgreSQL</productname> uses the widely-used IANA
time zone data for this purpose, so the same time zone time zone data for this purpose, so the same time zone
names are also recognized by much other software. names are also recognized by much other software.
@ -2417,9 +2417,9 @@ January 8 04:05:06 1999 PST
contrast to full time zone names which can imply a set of daylight contrast to full time zone names which can imply a set of daylight
savings transition-date rules as well. The recognized abbreviations savings transition-date rules as well. The recognized abbreviations
are listed in the <literal>pg_timezone_abbrevs</literal> view (see <xref are listed in the <literal>pg_timezone_abbrevs</literal> view (see <xref
linkend="view-pg-timezone-abbrevs">). You cannot set the linkend="view-pg-timezone-abbrevs"/>). You cannot set the
configuration parameters <xref linkend="guc-timezone"> or configuration parameters <xref linkend="guc-timezone"/> or
<xref linkend="guc-log-timezone"> to a time <xref linkend="guc-log-timezone"/> to a time
zone abbreviation, but you can use abbreviations in zone abbreviation, but you can use abbreviations in
date/time input values and with the <literal>AT TIME ZONE</literal> date/time input values and with the <literal>AT TIME ZONE</literal>
operator. operator.
@ -2499,13 +2499,13 @@ January 8 04:05:06 1999 PST
they are obtained from configuration files stored under they are obtained from configuration files stored under
<filename>.../share/timezone/</filename> and <filename>.../share/timezonesets/</filename> <filename>.../share/timezone/</filename> and <filename>.../share/timezonesets/</filename>
of the installation directory of the installation directory
(see <xref linkend="datetime-config-files">). (see <xref linkend="datetime-config-files"/>).
</para> </para>
<para> <para>
The <xref linkend="guc-timezone"> configuration parameter can The <xref linkend="guc-timezone"/> configuration parameter can
be set in the file <filename>postgresql.conf</filename>, or in any of the be set in the file <filename>postgresql.conf</filename>, or in any of the
other standard ways described in <xref linkend="runtime-config">. other standard ways described in <xref linkend="runtime-config"/>.
There are also some special ways to set it: There are also some special ways to set it:
<itemizedlist> <itemizedlist>
@ -2556,7 +2556,7 @@ January 8 04:05:06 1999 PST
of the different units are implicitly added with appropriate of the different units are implicitly added with appropriate
sign accounting. <literal>ago</literal> negates all the fields. sign accounting. <literal>ago</literal> negates all the fields.
This syntax is also used for interval output, if This syntax is also used for interval output, if
<xref linkend="guc-intervalstyle"> is set to <xref linkend="guc-intervalstyle"/> is set to
<literal>postgres_verbose</literal>. <literal>postgres_verbose</literal>.
</para> </para>
@ -2582,7 +2582,7 @@ P <replaceable>quantity</replaceable> <replaceable>unit</replaceable> <optional>
The string must start with a <literal>P</literal>, and may include a The string must start with a <literal>P</literal>, and may include a
<literal>T</literal> that introduces the time-of-day units. The <literal>T</literal> that introduces the time-of-day units. The
available unit abbreviations are given in <xref available unit abbreviations are given in <xref
linkend="datatype-interval-iso8601-units">. Units may be linkend="datatype-interval-iso8601-units"/>. Units may be
omitted, and may be specified in any order, but units smaller than omitted, and may be specified in any order, but units smaller than
a day must appear after <literal>T</literal>. In particular, the meaning of a day must appear after <literal>T</literal>. In particular, the meaning of
<literal>M</literal> depends on whether it is before or after <literal>M</literal> depends on whether it is before or after
@ -2696,7 +2696,7 @@ P <optional> <replaceable>years</replaceable>-<replaceable>months</replaceable>-
</para> </para>
<para> <para>
<xref linkend="datatype-interval-input-examples"> shows some examples <xref linkend="datatype-interval-input-examples"/> shows some examples
of valid <type>interval</type> input. of valid <type>interval</type> input.
</para> </para>
@ -2751,7 +2751,7 @@ P <optional> <replaceable>years</replaceable>-<replaceable>months</replaceable>-
<literal>postgres_verbose</literal>, or <literal>iso_8601</literal>, <literal>postgres_verbose</literal>, or <literal>iso_8601</literal>,
using the command <literal>SET intervalstyle</literal>. using the command <literal>SET intervalstyle</literal>.
The default is the <literal>postgres</literal> format. The default is the <literal>postgres</literal> format.
<xref linkend="interval-style-output-table"> shows examples of each <xref linkend="interval-style-output-table"/> shows examples of each
output style. output style.
</para> </para>
@ -2768,7 +2768,7 @@ P <optional> <replaceable>years</replaceable>-<replaceable>months</replaceable>-
<para> <para>
The output of the <literal>postgres</literal> style matches the output of The output of the <literal>postgres</literal> style matches the output of
<productname>PostgreSQL</productname> releases prior to 8.4 when the <productname>PostgreSQL</productname> releases prior to 8.4 when the
<xref linkend="guc-datestyle"> parameter was set to <literal>ISO</literal>. <xref linkend="guc-datestyle"/> parameter was set to <literal>ISO</literal>.
</para> </para>
<para> <para>
@ -2846,7 +2846,7 @@ P <optional> <replaceable>years</replaceable>-<replaceable>months</replaceable>-
<para> <para>
<productname>PostgreSQL</productname> provides the <productname>PostgreSQL</productname> provides the
standard <acronym>SQL</acronym> type <type>boolean</type>; standard <acronym>SQL</acronym> type <type>boolean</type>;
see <xref linkend="datatype-boolean-table">. see <xref linkend="datatype-boolean-table"/>.
The <type>boolean</type> type can have several states: The <type>boolean</type> type can have several states:
<quote>true</quote>, <quote>false</quote>, and a third state, <quote>true</quote>, <quote>false</quote>, and a third state,
<quote>unknown</quote>, which is represented by the <quote>unknown</quote>, which is represented by the
@ -2902,7 +2902,7 @@ P <optional> <replaceable>years</replaceable>-<replaceable>months</replaceable>-
</para> </para>
<para> <para>
<xref linkend="datatype-boolean-example"> shows that <xref linkend="datatype-boolean-example"/> shows that
<type>boolean</type> values are output using the letters <type>boolean</type> values are output using the letters
<literal>t</literal> and <literal>f</literal>. <literal>t</literal> and <literal>f</literal>.
</para> </para>
@ -2954,7 +2954,7 @@ SELECT * FROM test1 WHERE a;
<para> <para>
Enum types are created using the <xref Enum types are created using the <xref
linkend="sql-createtype"> command, linkend="sql-createtype"/> command,
for example: for example:
<programlisting> <programlisting>
@ -3087,7 +3087,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
<para> <para>
Geometric data types represent two-dimensional spatial Geometric data types represent two-dimensional spatial
objects. <xref linkend="datatype-geo-table"> shows the geometric objects. <xref linkend="datatype-geo-table"/> shows the geometric
types available in <productname>PostgreSQL</productname>. types available in <productname>PostgreSQL</productname>.
</para> </para>
@ -3158,7 +3158,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
<para> <para>
A rich set of functions and operators is available to perform various geometric A rich set of functions and operators is available to perform various geometric
operations such as scaling, translation, rotation, and determining operations such as scaling, translation, rotation, and determining
intersections. They are explained in <xref linkend="functions-geometry">. intersections. They are explained in <xref linkend="functions-geometry"/>.
</para> </para>
<sect2> <sect2>
@ -3410,11 +3410,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
<para> <para>
<productname>PostgreSQL</productname> offers data types to store IPv4, IPv6, and MAC <productname>PostgreSQL</productname> offers data types to store IPv4, IPv6, and MAC
addresses, as shown in <xref linkend="datatype-net-types-table">. It addresses, as shown in <xref linkend="datatype-net-types-table"/>. It
is better to use these types instead of plain text types to store is better to use these types instead of plain text types to store
network addresses, because network addresses, because
these types offer input error checking and specialized these types offer input error checking and specialized
operators and functions (see <xref linkend="functions-net">). operators and functions (see <xref linkend="functions-net"/>).
</para> </para>
<table tocentry="1" id="datatype-net-types-table"> <table tocentry="1" id="datatype-net-types-table">
@ -3526,7 +3526,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
</para> </para>
<para> <para>
<xref linkend="datatype-net-cidr-table"> shows some examples. <xref linkend="datatype-net-cidr-table"/> shows some examples.
</para> </para>
<table id="datatype-net-cidr-table"> <table id="datatype-net-cidr-table">
@ -3809,10 +3809,10 @@ SELECT macaddr8_set7bit('08:00:2b:01:02:03');
<para> <para>
Refer to <xref Refer to <xref
linkend="sql-syntax-bit-strings"> for information about the syntax linkend="sql-syntax-bit-strings"/> for information about the syntax
of bit string constants. Bit-logical operators and string of bit string constants. Bit-logical operators and string
manipulation functions are available; see <xref manipulation functions are available; see <xref
linkend="functions-bitstring">. linkend="functions-bitstring"/>.
</para> </para>
<example> <example>
@ -3840,7 +3840,7 @@ SELECT * FROM test;
A bit string value requires 1 byte for each group of 8 bits, plus A bit string value requires 1 byte for each group of 8 bits, plus
5 or 8 bytes overhead depending on the length of the string 5 or 8 bytes overhead depending on the length of the string
(but long values may be compressed or moved out-of-line, as explained (but long values may be compressed or moved out-of-line, as explained
in <xref linkend="datatype-character"> for character strings). in <xref linkend="datatype-character"/> for character strings).
</para> </para>
</sect1> </sect1>
@ -3865,8 +3865,8 @@ SELECT * FROM test;
The <type>tsvector</type> type represents a document in a form optimized The <type>tsvector</type> type represents a document in a form optimized
for text search; the <type>tsquery</type> type similarly represents for text search; the <type>tsquery</type> type similarly represents
a text query. a text query.
<xref linkend="textsearch"> provides a detailed explanation of this <xref linkend="textsearch"/> provides a detailed explanation of this
facility, and <xref linkend="functions-textsearch"> summarizes the facility, and <xref linkend="functions-textsearch"/> summarizes the
related functions and operators. related functions and operators.
</para> </para>
@ -3881,7 +3881,7 @@ SELECT * FROM test;
A <type>tsvector</type> value is a sorted list of distinct A <type>tsvector</type> value is a sorted list of distinct
<firstterm>lexemes</firstterm>, which are words that have been <firstterm>lexemes</firstterm>, which are words that have been
<firstterm>normalized</firstterm> to merge different variants of the same word <firstterm>normalized</firstterm> to merge different variants of the same word
(see <xref linkend="textsearch"> for details). Sorting and (see <xref linkend="textsearch"/> for details). Sorting and
duplicate-elimination are done automatically during input, as shown in duplicate-elimination are done automatically during input, as shown in
this example: this example:
@ -3975,7 +3975,7 @@ SELECT to_tsvector('english', 'The Fat Rats');
'fat':2 'rat':3 'fat':2 'rat':3
</programlisting> </programlisting>
Again, see <xref linkend="textsearch"> for more detail. Again, see <xref linkend="textsearch"/> for more detail.
</para> </para>
</sect2> </sect2>
@ -4140,9 +4140,9 @@ a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11
functions for UUIDs, but the core database does not include any functions for UUIDs, but the core database does not include any
function for generating UUIDs, because no single algorithm is well function for generating UUIDs, because no single algorithm is well
suited for every application. The <xref suited for every application. The <xref
linkend="uuid-ossp"> module linkend="uuid-ossp"/> module
provides functions that implement several standard algorithms. provides functions that implement several standard algorithms.
The <xref linkend="pgcrypto"> module also provides a generation The <xref linkend="pgcrypto"/> module also provides a generation
function for random UUIDs. function for random UUIDs.
Alternatively, UUIDs could be generated by client applications or Alternatively, UUIDs could be generated by client applications or
other libraries invoked through a server-side function. other libraries invoked through a server-side function.
@ -4161,7 +4161,7 @@ a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11
advantage over storing XML data in a <type>text</type> field is that it advantage over storing XML data in a <type>text</type> field is that it
checks the input values for well-formedness, and there are support checks the input values for well-formedness, and there are support
functions to perform type-safe operations on it; see <xref functions to perform type-safe operations on it; see <xref
linkend="functions-xml">. Use of this data type requires the linkend="functions-xml"/>. Use of this data type requires the
installation to have been built with <command>configure installation to have been built with <command>configure
--with-libxml</command>. --with-libxml</command>.
</para> </para>
@ -4267,7 +4267,7 @@ SET xmloption TO { DOCUMENT | CONTENT };
results to the client (which is the normal mode), PostgreSQL results to the client (which is the normal mode), PostgreSQL
converts all character data passed between the client and the converts all character data passed between the client and the
server and vice versa to the character encoding of the respective server and vice versa to the character encoding of the respective
end; see <xref linkend="multibyte">. This includes string end; see <xref linkend="multibyte"/>. This includes string
representations of XML values, such as in the above examples. representations of XML values, such as in the above examples.
This would ordinarily mean that encoding declarations contained in This would ordinarily mean that encoding declarations contained in
XML data can become invalid as the character data is converted XML data can become invalid as the character data is converted
@ -4408,7 +4408,7 @@ INSERT INTO mytable VALUES(-1); -- fails
</para> </para>
<para> <para>
For additional information see <xref linkend="sql-createdomain">. For additional information see <xref linkend="sql-createdomain"/>.
</para> </para>
</sect1> </sect1>
@ -4473,14 +4473,14 @@ INSERT INTO mytable VALUES(-1); -- fails
<productname>PostgreSQL</productname> as primary keys for various <productname>PostgreSQL</productname> as primary keys for various
system tables. OIDs are not added to user-created tables, unless system tables. OIDs are not added to user-created tables, unless
<literal>WITH OIDS</literal> is specified when the table is <literal>WITH OIDS</literal> is specified when the table is
created, or the <xref linkend="guc-default-with-oids"> created, or the <xref linkend="guc-default-with-oids"/>
configuration variable is enabled. Type <type>oid</type> represents configuration variable is enabled. Type <type>oid</type> represents
an object identifier. There are also several alias types for an object identifier. There are also several alias types for
<type>oid</type>: <type>regproc</type>, <type>regprocedure</type>, <type>oid</type>: <type>regproc</type>, <type>regprocedure</type>,
<type>regoper</type>, <type>regoperator</type>, <type>regclass</type>, <type>regoper</type>, <type>regoperator</type>, <type>regclass</type>,
<type>regtype</type>, <type>regrole</type>, <type>regnamespace</type>, <type>regtype</type>, <type>regrole</type>, <type>regnamespace</type>,
<type>regconfig</type>, and <type>regdictionary</type>. <type>regconfig</type>, and <type>regdictionary</type>.
<xref linkend="datatype-oid-table"> shows an overview. <xref linkend="datatype-oid-table"/> shows an overview.
</para> </para>
<para> <para>
@ -4677,7 +4677,7 @@ SELECT * FROM pg_attribute
<para> <para>
(The system columns are further explained in <xref (The system columns are further explained in <xref
linkend="ddl-system-columns">.) linkend="ddl-system-columns"/>.)
</para> </para>
</sect1> </sect1>
@ -4795,7 +4795,7 @@ SELECT * FROM pg_attribute
useful in situations where a function's behavior does not useful in situations where a function's behavior does not
correspond to simply taking or returning a value of a specific correspond to simply taking or returning a value of a specific
<acronym>SQL</acronym> data type. <xref <acronym>SQL</acronym> data type. <xref
linkend="datatype-pseudotypes-table"> lists the existing linkend="datatype-pseudotypes-table"/> lists the existing
pseudo-types. pseudo-types.
</para> </para>
@ -4818,33 +4818,33 @@ SELECT * FROM pg_attribute
<row> <row>
<entry><type>anyelement</type></entry> <entry><type>anyelement</type></entry>
<entry>Indicates that a function accepts any data type <entry>Indicates that a function accepts any data type
(see <xref linkend="extend-types-polymorphic">).</entry> (see <xref linkend="extend-types-polymorphic"/>).</entry>
</row> </row>
<row> <row>
<entry><type>anyarray</type></entry> <entry><type>anyarray</type></entry>
<entry>Indicates that a function accepts any array data type <entry>Indicates that a function accepts any array data type
(see <xref linkend="extend-types-polymorphic">).</entry> (see <xref linkend="extend-types-polymorphic"/>).</entry>
</row> </row>
<row> <row>
<entry><type>anynonarray</type></entry> <entry><type>anynonarray</type></entry>
<entry>Indicates that a function accepts any non-array data type <entry>Indicates that a function accepts any non-array data type
(see <xref linkend="extend-types-polymorphic">).</entry> (see <xref linkend="extend-types-polymorphic"/>).</entry>
</row> </row>
<row> <row>
<entry><type>anyenum</type></entry> <entry><type>anyenum</type></entry>
<entry>Indicates that a function accepts any enum data type <entry>Indicates that a function accepts any enum data type
(see <xref linkend="extend-types-polymorphic"> and (see <xref linkend="extend-types-polymorphic"/> and
<xref linkend="datatype-enum">).</entry> <xref linkend="datatype-enum"/>).</entry>
</row> </row>
<row> <row>
<entry><type>anyrange</type></entry> <entry><type>anyrange</type></entry>
<entry>Indicates that a function accepts any range data type <entry>Indicates that a function accepts any range data type
(see <xref linkend="extend-types-polymorphic"> and (see <xref linkend="extend-types-polymorphic"/> and
<xref linkend="rangetypes">).</entry> <xref linkend="rangetypes"/>).</entry>
</row> </row>
<row> <row>

8
doc/src/sgml/datetime.sgml
View File

@ -180,7 +180,7 @@
<title>Date/Time Key Words</title> <title>Date/Time Key Words</title>
<para> <para>
<xref linkend="datetime-month-table"> shows the tokens that are <xref linkend="datetime-month-table"/> shows the tokens that are
recognized as names of months. recognized as names of months.
</para> </para>
@ -247,7 +247,7 @@
</table> </table>
<para> <para>
<xref linkend="datetime-dow-table"> shows the tokens that are <xref linkend="datetime-dow-table"/> shows the tokens that are
recognized as names of days of the week. recognized as names of days of the week.
</para> </para>
@ -294,7 +294,7 @@
</table> </table>
<para> <para>
<xref linkend="datetime-mod-table"> shows the tokens that serve <xref linkend="datetime-mod-table"/> shows the tokens that serve
various modifier purposes. various modifier purposes.
</para> </para>
@ -349,7 +349,7 @@
Since timezone abbreviations are not well standardized, Since timezone abbreviations are not well standardized,
<productname>PostgreSQL</productname> provides a means to customize <productname>PostgreSQL</productname> provides a means to customize
the set of abbreviations accepted by the server. The the set of abbreviations accepted by the server. The
<xref linkend="guc-timezone-abbreviations"> run-time parameter <xref linkend="guc-timezone-abbreviations"/> run-time parameter
determines the active set of abbreviations. While this parameter determines the active set of abbreviations. While this parameter
can be altered by any database user, the possible values for it can be altered by any database user, the possible values for it
are under the control of the database administrator &mdash; they are under the control of the database administrator &mdash; they

10
doc/src/sgml/dblink.sgml
View File

@ -14,7 +14,7 @@
</para> </para>
<para> <para>
See also <xref linkend="postgres-fdw">, which provides roughly the same See also <xref linkend="postgres-fdw"/>, which provides roughly the same
functionality using a more modern and standards-compliant infrastructure. functionality using a more modern and standards-compliant infrastructure.
</para> </para>
@ -58,8 +58,8 @@ dblink_connect(text connname, text connstr) returns text
server. It is recommended to use the foreign-data wrapper server. It is recommended to use the foreign-data wrapper
<literal>dblink_fdw</literal> when defining the foreign <literal>dblink_fdw</literal> when defining the foreign
server. See the example below, as well as server. See the example below, as well as
<xref linkend="sql-createserver"> and <xref linkend="sql-createserver"/> and
<xref linkend="sql-createusermapping">. <xref linkend="sql-createusermapping"/>.
</para> </para>
</refsect1> </refsect1>
@ -84,7 +84,7 @@ dblink_connect(text connname, text connstr) returns text
<para><application>libpq</application>-style connection info string, for example <para><application>libpq</application>-style connection info string, for example
<literal>hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres <literal>hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres
password=mypasswd</literal>. password=mypasswd</literal>.
For details see <xref linkend="libpq-connstring">. For details see <xref linkend="libpq-connstring"/>.
Alternatively, the name of a foreign server. Alternatively, the name of a foreign server.
</para> </para>
</listitem> </listitem>
@ -1340,7 +1340,7 @@ dblink_get_notify(text connname) returns setof (notify_name text, be_pid int, ex
the unnamed connection, or on a named connection if specified. the unnamed connection, or on a named connection if specified.
To receive notifications via dblink, <function>LISTEN</function> must To receive notifications via dblink, <function>LISTEN</function> must
first be issued, using <function>dblink_exec</function>. first be issued, using <function>dblink_exec</function>.
For details see <xref linkend="sql-listen"> and <xref linkend="sql-notify">. For details see <xref linkend="sql-listen"/> and <xref linkend="sql-notify"/>.
</para> </para>
</refsect1> </refsect1>

126
doc/src/sgml/ddl.sgml
View File

@ -39,7 +39,7 @@
SQL does not make any guarantees about the order of the rows in a SQL does not make any guarantees about the order of the rows in a
table. When a table is read, the rows will appear in an unspecified order, table. When a table is read, the rows will appear in an unspecified order,
unless sorting is explicitly requested. This is covered in <xref unless sorting is explicitly requested. This is covered in <xref
linkend="queries">. Furthermore, SQL does not assign unique linkend="queries"/>. Furthermore, SQL does not assign unique
identifiers to rows, so it is possible to have several completely identifiers to rows, so it is possible to have several completely
identical rows in a table. This is a consequence of the identical rows in a table. This is a consequence of the
mathematical model that underlies SQL but is usually not desirable. mathematical model that underlies SQL but is usually not desirable.
@ -64,7 +64,7 @@
built-in data types that fit many applications. Users can also built-in data types that fit many applications. Users can also
define their own data types. Most built-in data types have obvious define their own data types. Most built-in data types have obvious
names and semantics, so we defer a detailed explanation to <xref names and semantics, so we defer a detailed explanation to <xref
linkend="datatype">. Some of the frequently used data types are linkend="datatype"/>. Some of the frequently used data types are
<type>integer</type> for whole numbers, <type>numeric</type> for <type>integer</type> for whole numbers, <type>numeric</type> for
possibly fractional numbers, <type>text</type> for character possibly fractional numbers, <type>text</type> for character
strings, <type>date</type> for dates, <type>time</type> for strings, <type>date</type> for dates, <type>time</type> for
@ -79,7 +79,7 @@
<para> <para>
To create a table, you use the aptly named <xref To create a table, you use the aptly named <xref
linkend="sql-createtable"> command. linkend="sql-createtable"/> command.
In this command you specify at least a name for the new table, the In this command you specify at least a name for the new table, the
names of the columns and the data type of each column. For names of the columns and the data type of each column. For
example: example:
@ -95,7 +95,7 @@ CREATE TABLE my_first_table (
<type>text</type>; the second column has the name <type>text</type>; the second column has the name
<literal>second_column</literal> and the type <type>integer</type>. <literal>second_column</literal> and the type <type>integer</type>.
The table and column names follow the identifier syntax explained The table and column names follow the identifier syntax explained
in <xref linkend="sql-syntax-identifiers">. The type names are in <xref linkend="sql-syntax-identifiers"/>. The type names are
usually also identifiers, but there are some exceptions. Note that the usually also identifiers, but there are some exceptions. Note that the
column list is comma-separated and surrounded by parentheses. column list is comma-separated and surrounded by parentheses.
</para> </para>
@ -139,7 +139,7 @@ CREATE TABLE products (
<para> <para>
If you no longer need a table, you can remove it using the <xref If you no longer need a table, you can remove it using the <xref
linkend="sql-droptable"> command. linkend="sql-droptable"/> command.
For example: For example:
<programlisting> <programlisting>
DROP TABLE my_first_table; DROP TABLE my_first_table;
@ -155,7 +155,7 @@ DROP TABLE products;
<para> <para>
If you need to modify a table that already exists, see <xref If you need to modify a table that already exists, see <xref
linkend="ddl-alter"> later in this chapter. linkend="ddl-alter"/> later in this chapter.
</para> </para>
<para> <para>
@ -163,7 +163,7 @@ DROP TABLE products;
tables. The remainder of this chapter is concerned with adding tables. The remainder of this chapter is concerned with adding
features to the table definition to ensure data integrity, features to the table definition to ensure data integrity,
security, or convenience. If you are eager to fill your tables with security, or convenience. If you are eager to fill your tables with
data now you can skip ahead to <xref linkend="dml"> and read the data now you can skip ahead to <xref linkend="dml"/> and read the
rest of this chapter later. rest of this chapter later.
</para> </para>
</sect1> </sect1>
@ -181,7 +181,7 @@ DROP TABLE products;
columns will be filled with their respective default values. A columns will be filled with their respective default values. A
data manipulation command can also request explicitly that a column data manipulation command can also request explicitly that a column
be set to its default value, without having to know what that value is. be set to its default value, without having to know what that value is.
(Details about data manipulation commands are in <xref linkend="dml">.) (Details about data manipulation commands are in <xref linkend="dml"/>.)
</para> </para>
<para> <para>
@ -220,7 +220,7 @@ CREATE TABLE products (
</programlisting> </programlisting>
where the <literal>nextval()</literal> function supplies successive values where the <literal>nextval()</literal> function supplies successive values
from a <firstterm>sequence object</firstterm> (see <xref from a <firstterm>sequence object</firstterm> (see <xref
linkend="functions-sequence">). This arrangement is sufficiently common linkend="functions-sequence"/>). This arrangement is sufficiently common
that there's a special shorthand for it: that there's a special shorthand for it:
<programlisting> <programlisting>
CREATE TABLE products ( CREATE TABLE products (
@ -229,7 +229,7 @@ CREATE TABLE products (
); );
</programlisting> </programlisting>
The <literal>SERIAL</literal> shorthand is discussed further in <xref The <literal>SERIAL</literal> shorthand is discussed further in <xref
linkend="datatype-serial">. linkend="datatype-serial"/>.
</para> </para>
</sect1> </sect1>
@ -876,9 +876,9 @@ CREATE TABLE order_items (
<para> <para>
More information about updating and deleting data is in <xref More information about updating and deleting data is in <xref
linkend="dml">. Also see the description of foreign key constraint linkend="dml"/>. Also see the description of foreign key constraint
syntax in the reference documentation for syntax in the reference documentation for
<xref linkend="sql-createtable">. <xref linkend="sql-createtable"/>.
</para> </para>
</sect2> </sect2>
@ -948,10 +948,10 @@ CREATE TABLE circles (
</indexterm> </indexterm>
The object identifier (object ID) of a row. This column is only The object identifier (object ID) of a row. This column is only
present if the table was created using <literal>WITH present if the table was created using <literal>WITH
OIDS</literal>, or if the <xref linkend="guc-default-with-oids"> OIDS</literal>, or if the <xref linkend="guc-default-with-oids"/>
configuration variable was set at the time. This column is of type configuration variable was set at the time. This column is of type
<type>oid</type> (same name as the column); see <xref <type>oid</type> (same name as the column); see <xref
linkend="datatype-oid"> for more information about the type. linkend="datatype-oid"/> for more information about the type.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -966,7 +966,7 @@ CREATE TABLE circles (
<para> <para>
The OID of the table containing this row. This column is The OID of the table containing this row. This column is
particularly handy for queries that select from inheritance particularly handy for queries that select from inheritance
hierarchies (see <xref linkend="ddl-inherit">), since without it, hierarchies (see <xref linkend="ddl-inherit"/>), since without it,
it's difficult to tell which individual table a row came from. The it's difficult to tell which individual table a row came from. The
<structfield>tableoid</structfield> can be joined against the <structfield>tableoid</structfield> can be joined against the
<structfield>oid</structfield> column of <structfield>oid</structfield> column of
@ -1100,7 +1100,7 @@ CREATE TABLE circles (
Transaction identifiers are also 32-bit quantities. In a Transaction identifiers are also 32-bit quantities. In a
long-lived database it is possible for transaction IDs to wrap long-lived database it is possible for transaction IDs to wrap
around. This is not a fatal problem given appropriate maintenance around. This is not a fatal problem given appropriate maintenance
procedures; see <xref linkend="maintenance"> for details. It is procedures; see <xref linkend="maintenance"/> for details. It is
unwise, however, to depend on the uniqueness of transaction IDs unwise, however, to depend on the uniqueness of transaction IDs
over the long term (more than one billion transactions). over the long term (more than one billion transactions).
</para> </para>
@ -1167,7 +1167,7 @@ CREATE TABLE circles (
</itemizedlist> </itemizedlist>
All these actions are performed using the All these actions are performed using the
<xref linkend="sql-altertable"> <xref linkend="sql-altertable"/>
command, whose reference page contains details beyond those given command, whose reference page contains details beyond those given
here. here.
</para> </para>
@ -1238,7 +1238,7 @@ ALTER TABLE products DROP COLUMN description;
<programlisting> <programlisting>
ALTER TABLE products DROP COLUMN description CASCADE; ALTER TABLE products DROP COLUMN description CASCADE;
</programlisting> </programlisting>
See <xref linkend="ddl-depend"> for a description of the general See <xref linkend="ddl-depend"/> for a description of the general
mechanism behind this. mechanism behind this.
</para> </para>
</sect2> </sect2>
@ -1446,7 +1446,7 @@ ALTER TABLE products RENAME TO items;
object vary depending on the object's type (table, function, etc). object vary depending on the object's type (table, function, etc).
For complete information on the different types of privileges For complete information on the different types of privileges
supported by <productname>PostgreSQL</productname>, refer to the supported by <productname>PostgreSQL</productname>, refer to the
<xref linkend="sql-grant"> reference <xref linkend="sql-grant"/> reference
page. The following sections and chapters will also show you how page. The following sections and chapters will also show you how
those privileges are used. those privileges are used.
</para> </para>
@ -1459,7 +1459,7 @@ ALTER TABLE products RENAME TO items;
<para> <para>
An object can be assigned to a new owner with an <command>ALTER</command> An object can be assigned to a new owner with an <command>ALTER</command>
command of the appropriate kind for the object, e.g. <xref command of the appropriate kind for the object, e.g. <xref
linkend="sql-altertable">. Superusers can always do linkend="sql-altertable"/>. Superusers can always do
this; ordinary roles can only do it if they are both the current owner this; ordinary roles can only do it if they are both the current owner
of the object (or a member of the owning role) and a member of the new of the object (or a member of the owning role) and a member of the new
owning role. owning role.
@ -1482,7 +1482,7 @@ GRANT UPDATE ON accounts TO joe;
be used to grant a privilege to every role on the system. Also, be used to grant a privilege to every role on the system. Also,
<quote>group</quote> roles can be set up to help manage privileges when <quote>group</quote> roles can be set up to help manage privileges when
there are many users of a database &mdash; for details see there are many users of a database &mdash; for details see
<xref linkend="user-manag">. <xref linkend="user-manag"/>.
</para> </para>
<para> <para>
@ -1506,8 +1506,8 @@ REVOKE ALL ON accounts FROM PUBLIC;
the right to grant it in turn to others. If the grant option is the right to grant it in turn to others. If the grant option is
subsequently revoked then all who received the privilege from that subsequently revoked then all who received the privilege from that
recipient (directly or through a chain of grants) will lose the recipient (directly or through a chain of grants) will lose the
privilege. For details see the <xref linkend="sql-grant"> and privilege. For details see the <xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"> reference pages. <xref linkend="sql-revoke"/> reference pages.
</para> </para>
</sect1> </sect1>
@ -1524,7 +1524,7 @@ REVOKE ALL ON accounts FROM PUBLIC;
<para> <para>
In addition to the SQL-standard <link linkend="ddl-priv">privilege In addition to the SQL-standard <link linkend="ddl-priv">privilege
system</link> available through <xref linkend="sql-grant">, system</link> available through <xref linkend="sql-grant"/>,
tables can have <firstterm>row security policies</firstterm> that restrict, tables can have <firstterm>row security policies</firstterm> that restrict,
on a per-user basis, which rows can be returned by normal queries on a per-user basis, which rows can be returned by normal queries
or inserted, updated, or deleted by data modification commands. or inserted, updated, or deleted by data modification commands.
@ -1584,11 +1584,11 @@ REVOKE ALL ON accounts FROM PUBLIC;
</para> </para>
<para> <para>
Policies are created using the <xref linkend="sql-createpolicy"> Policies are created using the <xref linkend="sql-createpolicy"/>
command, altered using the <xref linkend="sql-alterpolicy"> command, command, altered using the <xref linkend="sql-alterpolicy"/> command,
and dropped using the <xref linkend="sql-droppolicy"> command. To and dropped using the <xref linkend="sql-droppolicy"/> command. To
enable and disable row security for a given table, use the enable and disable row security for a given table, use the
<xref linkend="sql-altertable"> command. <xref linkend="sql-altertable"/> command.
</para> </para>
<para> <para>
@ -1829,7 +1829,7 @@ UPDATE 0
not being applied. For example, when taking a backup, it could be not being applied. For example, when taking a backup, it could be
disastrous if row security silently caused some rows to be omitted disastrous if row security silently caused some rows to be omitted
from the backup. In such a situation, you can set the from the backup. In such a situation, you can set the
<xref linkend="guc-row-security"> configuration parameter <xref linkend="guc-row-security"/> configuration parameter
to <literal>off</literal>. This does not in itself bypass row security; to <literal>off</literal>. This does not in itself bypass row security;
what it does is throw an error if any query's results would get filtered what it does is throw an error if any query's results would get filtered
by a policy. The reason for the error can then be investigated and by a policy. The reason for the error can then be investigated and
@ -1951,8 +1951,8 @@ SELECT * FROM information WHERE group_id = 2 FOR UPDATE;
</para> </para>
<para> <para>
For additional details see <xref linkend="sql-createpolicy"> For additional details see <xref linkend="sql-createpolicy"/>
and <xref linkend="sql-altertable">. and <xref linkend="sql-altertable"/>.
</para> </para>
</sect1> </sect1>
@ -2034,7 +2034,7 @@ SELECT * FROM information WHERE group_id = 2 FOR UPDATE;
</indexterm> </indexterm>
<para> <para>
To create a schema, use the <xref linkend="sql-createschema"> To create a schema, use the <xref linkend="sql-createschema"/>
command. Give the schema a name command. Give the schema a name
of your choice. For example: of your choice. For example:
<programlisting> <programlisting>
@ -2099,7 +2099,7 @@ DROP SCHEMA myschema;
<programlisting> <programlisting>
DROP SCHEMA myschema CASCADE; DROP SCHEMA myschema CASCADE;
</programlisting> </programlisting>
See <xref linkend="ddl-depend"> for a description of the general See <xref linkend="ddl-depend"/> for a description of the general
mechanism behind this. mechanism behind this.
</para> </para>
@ -2112,7 +2112,7 @@ CREATE SCHEMA <replaceable>schema_name</replaceable> AUTHORIZATION <replaceable>
</programlisting> </programlisting>
You can even omit the schema name, in which case the schema name You can even omit the schema name, in which case the schema name
will be the same as the user name. See <xref will be the same as the user name. See <xref
linkend="ddl-schemas-patterns"> for how this can be useful. linkend="ddl-schemas-patterns"/> for how this can be useful.
</para> </para>
<para> <para>
@ -2242,7 +2242,7 @@ SET search_path TO myschema;
</para> </para>
<para> <para>
See also <xref linkend="functions-info"> for other ways to manipulate See also <xref linkend="functions-info"/> for other ways to manipulate
the schema search path. the schema search path.
</para> </para>
@ -2297,7 +2297,7 @@ REVOKE CREATE ON SCHEMA public FROM PUBLIC;
<quote>public</quote> means <quote>every user</quote>. In the <quote>public</quote> means <quote>every user</quote>. In the
first sense it is an identifier, in the second sense it is a first sense it is an identifier, in the second sense it is a
key word, hence the different capitalization; recall the key word, hence the different capitalization; recall the
guidelines from <xref linkend="sql-syntax-identifiers">.) guidelines from <xref linkend="sql-syntax-identifiers"/>.)
</para> </para>
</sect2> </sect2>
@ -2483,7 +2483,7 @@ SELECT name, altitude
</programlisting> </programlisting>
Given the sample data from the <productname>PostgreSQL</productname> Given the sample data from the <productname>PostgreSQL</productname>
tutorial (see <xref linkend="tutorial-sql-intro">), this returns: tutorial (see <xref linkend="tutorial-sql-intro"/>), this returns:
<programlisting> <programlisting>
name | altitude name | altitude
@ -2602,7 +2602,7 @@ VALUES ('Albany', NULL, NULL, 'NY');
<structname>capitals</structname> table, but this does not happen: <structname>capitals</structname> table, but this does not happen:
<command>INSERT</command> always inserts into exactly the table <command>INSERT</command> always inserts into exactly the table
specified. In some cases it is possible to redirect the insertion specified. In some cases it is possible to redirect the insertion
using a rule (see <xref linkend="rules">). However that does not using a rule (see <xref linkend="rules"/>). However that does not
help for the above case because the <structname>cities</structname> table help for the above case because the <structname>cities</structname> table
does not contain the column <structfield>state</structfield>, and so the does not contain the column <structfield>state</structfield>, and so the
command will be rejected before the rule can be applied. command will be rejected before the rule can be applied.
@ -2633,11 +2633,11 @@ VALUES ('Albany', NULL, NULL, 'NY');
<para> <para>
Table inheritance is typically established when the child table is Table inheritance is typically established when the child table is
created, using the <literal>INHERITS</literal> clause of the created, using the <literal>INHERITS</literal> clause of the
<xref linkend="sql-createtable"> <xref linkend="sql-createtable"/>
statement. statement.
Alternatively, a table which is already defined in a compatible way can Alternatively, a table which is already defined in a compatible way can
have a new parent relationship added, using the <literal>INHERIT</literal> have a new parent relationship added, using the <literal>INHERIT</literal>
variant of <xref linkend="sql-altertable">. variant of <xref linkend="sql-altertable"/>.
To do this the new child table must already include columns with To do this the new child table must already include columns with
the same names and types as the columns of the parent. It must also include the same names and types as the columns of the parent. It must also include
check constraints with the same names and check expressions as those of the check constraints with the same names and check expressions as those of the
@ -2645,7 +2645,7 @@ VALUES ('Albany', NULL, NULL, 'NY');
<literal>NO INHERIT</literal> variant of <command>ALTER TABLE</command>. <literal>NO INHERIT</literal> variant of <command>ALTER TABLE</command>.
Dynamically adding and removing inheritance links like this can be useful Dynamically adding and removing inheritance links like this can be useful
when the inheritance relationship is being used for table when the inheritance relationship is being used for table
partitioning (see <xref linkend="ddl-partitioning">). partitioning (see <xref linkend="ddl-partitioning"/>).
</para> </para>
<para> <para>
@ -2665,11 +2665,11 @@ VALUES ('Albany', NULL, NULL, 'NY');
if they are inherited if they are inherited
from any parent tables. If you wish to remove a table and all of its from any parent tables. If you wish to remove a table and all of its
descendants, one easy way is to drop the parent table with the descendants, one easy way is to drop the parent table with the
<literal>CASCADE</literal> option (see <xref linkend="ddl-depend">). <literal>CASCADE</literal> option (see <xref linkend="ddl-depend"/>).
</para> </para>
<para> <para>
<xref linkend="sql-altertable"> will <xref linkend="sql-altertable"/> will
propagate any changes in column data definitions and check propagate any changes in column data definitions and check
constraints down the inheritance hierarchy. Again, dropping constraints down the inheritance hierarchy. Again, dropping
columns that are depended on by other tables is only possible when using columns that are depended on by other tables is only possible when using
@ -2687,7 +2687,7 @@ VALUES ('Albany', NULL, NULL, 'NY');
that the data is (also) in the parent table. But that the data is (also) in the parent table. But
the <structname>capitals</structname> table could not be updated directly the <structname>capitals</structname> table could not be updated directly
without an additional grant. In a similar way, the parent table's row without an additional grant. In a similar way, the parent table's row
security policies (see <xref linkend="ddl-rowsecurity">) are applied to security policies (see <xref linkend="ddl-rowsecurity"/>) are applied to
rows coming from child tables during an inherited query. A child table's 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 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 in the query; and in that case, any policies attached to its parent(s) are
@ -2695,7 +2695,7 @@ VALUES ('Albany', NULL, NULL, 'NY');
</para> </para>
<para> <para>
Foreign tables (see <xref linkend="ddl-foreign-data">) can also Foreign tables (see <xref linkend="ddl-foreign-data"/>) can also
be part of inheritance hierarchies, either as parent or child be part of inheritance hierarchies, either as parent or child
tables, just as regular tables can be. If a foreign table is part tables, just as regular tables can be. If a foreign table is part
of an inheritance hierarchy then any operations not supported by of an inheritance hierarchy then any operations not supported by
@ -2719,7 +2719,7 @@ VALUES ('Albany', NULL, NULL, 'NY');
typically only work on individual, physical tables and do not typically only work on individual, physical tables and do not
support recursing over inheritance hierarchies. The respective support recursing over inheritance hierarchies. The respective
behavior of each individual command is documented in its reference behavior of each individual command is documented in its reference
page (<xref linkend="sql-commands">). page (<xref linkend="sql-commands"/>).
</para> </para>
<para> <para>
@ -2923,7 +2923,7 @@ VALUES ('Albany', NULL, NULL, 'NY');
called <firstterm>sub-partitioning</firstterm>. Partitions may have their called <firstterm>sub-partitioning</firstterm>. Partitions may have their
own indexes, constraints and default values, distinct from those of other own indexes, constraints and default values, distinct from those of other
partitions. Indexes must be created separately for each partition. See partitions. Indexes must be created separately for each partition. See
<xref linkend="sql-createtable"> for more details on creating partitioned <xref linkend="sql-createtable"/> for more details on creating partitioned
tables and partitions. tables and partitions.
</para> </para>
@ -2932,7 +2932,7 @@ VALUES ('Albany', NULL, NULL, 'NY');
vice versa. However, it is possible to add a regular or partitioned table 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 containing data as a partition of a partitioned table, or remove a
partition from a partitioned table turning it into a standalone table; partition from a partitioned table turning it into a standalone table;
see <xref linkend="sql-altertable"> to learn more about the see <xref linkend="sql-altertable"/> to learn more about the
<command>ATTACH PARTITION</command> and <command>DETACH PARTITION</command> <command>ATTACH PARTITION</command> and <command>DETACH PARTITION</command>
sub-commands. sub-commands.
</para> </para>
@ -2948,7 +2948,7 @@ VALUES ('Albany', NULL, NULL, 'NY');
inheritance with regular tables. Since a partition hierarchy consisting inheritance with regular tables. Since a partition hierarchy consisting
of the partitioned table and its partitions is still an inheritance of the partitioned table and its partitions is still an inheritance
hierarchy, all the normal rules of inheritance apply as described in hierarchy, all the normal rules of inheritance apply as described in
<xref linkend="ddl-inherit"> with some exceptions, most notably: <xref linkend="ddl-inherit"/> with some exceptions, most notably:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -2999,7 +2999,7 @@ VALUES ('Albany', NULL, NULL, 'NY');
<para> <para>
Partitions can also be foreign tables Partitions can also be foreign tables
(see <xref linkend="sql-createforeigntable">), (see <xref linkend="sql-createforeigntable"/>),
although these have some limitations that normal tables do not. For although these have some limitations that normal tables do not. For
example, data inserted into the partitioned table is not routed to example, data inserted into the partitioned table is not routed to
foreign table partitions. foreign table partitions.
@ -3158,7 +3158,7 @@ CREATE INDEX ON measurement_y2008m01 (logdate);
<listitem> <listitem>
<para> <para>
Ensure that the <xref linkend="guc-constraint-exclusion"> Ensure that the <xref linkend="guc-constraint-exclusion"/>
configuration parameter is not disabled in <filename>postgresql.conf</filename>. configuration parameter is not disabled in <filename>postgresql.conf</filename>.
If it is, queries will not be optimized as desired. If it is, queries will not be optimized as desired.
</para> </para>
@ -3595,7 +3595,7 @@ DO INSTEAD
<listitem> <listitem>
<para> <para>
Ensure that the <xref linkend="guc-constraint-exclusion"> Ensure that the <xref linkend="guc-constraint-exclusion"/>
configuration parameter is not disabled in configuration parameter is not disabled in
<filename>postgresql.conf</filename>. <filename>postgresql.conf</filename>.
If it is, queries will not be optimized as desired. If it is, queries will not be optimized as desired.
@ -3806,7 +3806,7 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate &gt;= DATE '2008-01-01';
<para> <para>
The default (and recommended) setting of The default (and recommended) setting of
<xref linkend="guc-constraint-exclusion"> is actually neither <xref linkend="guc-constraint-exclusion"/> is actually neither
<literal>on</literal> nor <literal>off</literal>, but an intermediate setting <literal>on</literal> nor <literal>off</literal>, but an intermediate setting
called <literal>partition</literal>, which causes the technique to be called <literal>partition</literal>, which causes the technique to be
applied only to queries that are likely to be working on partitioned applied only to queries that are likely to be working on partitioned
@ -3889,10 +3889,10 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate &gt;= DATE '2008-01-01';
library that can communicate with an external data source, hiding the library that can communicate with an external data source, hiding the
details of connecting to the data source and obtaining data from it. details of connecting to the data source and obtaining data from it.
There are some foreign data wrappers available as <filename>contrib</filename> There are some foreign data wrappers available as <filename>contrib</filename>
modules; see <xref linkend="contrib">. Other kinds of foreign data modules; see <xref linkend="contrib"/>. Other kinds of foreign data
wrappers might be found as third party products. If none of the existing wrappers might be found as third party products. If none of the existing
foreign data wrappers suit your needs, you can write your own; see <xref foreign data wrappers suit your needs, you can write your own; see <xref
linkend="fdwhandler">. linkend="fdwhandler"/>.
</para> </para>
<para> <para>
@ -3918,11 +3918,11 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate &gt;= DATE '2008-01-01';
<para> <para>
For additional information, see For additional information, see
<xref linkend="sql-createforeigndatawrapper">, <xref linkend="sql-createforeigndatawrapper"/>,
<xref linkend="sql-createserver">, <xref linkend="sql-createserver"/>,
<xref linkend="sql-createusermapping">, <xref linkend="sql-createusermapping"/>,
<xref linkend="sql-createforeigntable">, and <xref linkend="sql-createforeigntable"/>, and
<xref linkend="sql-importforeignschema">. <xref linkend="sql-importforeignschema"/>.
</para> </para>
</sect1> </sect1>
@ -3966,7 +3966,7 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate &gt;= DATE '2008-01-01';
<para> <para>
Detailed information on Detailed information on
these topics appears in <xref linkend="server-programming">. these topics appears in <xref linkend="server-programming"/>.
</para> </para>
</sect1> </sect1>
@ -3996,7 +3996,7 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate &gt;= DATE '2008-01-01';
<productname>PostgreSQL</productname> makes sure that you cannot <productname>PostgreSQL</productname> makes sure that you cannot
drop objects that other objects still depend on. For example, drop objects that other objects still depend on. For example,
attempting to drop the products table we considered in <xref attempting to drop the products table we considered in <xref
linkend="ddl-constraints-fk">, with the orders table depending on linkend="ddl-constraints-fk"/>, with the orders table depending on
it, would result in an error message like this: it, would result in an error message like this:
<screen> <screen>
DROP TABLE products; DROP TABLE products;
@ -4066,7 +4066,7 @@ CREATE FUNCTION get_color_note (rainbow) RETURNS text AS
LANGUAGE SQL; LANGUAGE SQL;
</programlisting> </programlisting>
(See <xref linkend="xfunc-sql"> for an explanation of SQL-language (See <xref linkend="xfunc-sql"/> for an explanation of SQL-language
functions.) <productname>PostgreSQL</productname> will be aware that functions.) <productname>PostgreSQL</productname> will be aware that
the <function>get_color_note</function> function depends on the <type>rainbow</type> the <function>get_color_note</function> function depends on the <type>rainbow</type>
type: dropping the type would force dropping the function, because its type: dropping the type would force dropping the function, because its

2
doc/src/sgml/dfunc.sgml
View File

@ -226,7 +226,7 @@ gcc -G -o foo.so foo.o
</para> </para>
<para> <para>
Refer back to <xref linkend="xfunc-c-dynload"> about where the Refer back to <xref linkend="xfunc-c-dynload"/> about where the
server expects to find the shared library files. server expects to find the shared library files.
</para> </para>

2
doc/src/sgml/dict-int.sgml
View File

@ -71,7 +71,7 @@ mydb# select ts_lexize('intdict', '12345678');
</programlisting> </programlisting>
but real-world usage will involve including it in a text search but real-world usage will involve including it in a text search
configuration as described in <xref linkend="textsearch">. configuration as described in <xref linkend="textsearch"/>.
That might look like this: That might look like this:
<programlisting> <programlisting>

2
doc/src/sgml/dict-xsyn.sgml
View File

@ -135,7 +135,7 @@ mydb=# SELECT ts_lexize('xsyn', 'syn1');
</programlisting> </programlisting>
Real-world usage will involve including it in a text search Real-world usage will involve including it in a text search
configuration as described in <xref linkend="textsearch">. configuration as described in <xref linkend="textsearch"/>.
That might look like this: That might look like this:
<programlisting> <programlisting>

10
doc/src/sgml/diskusage.sgml
View File

@ -20,18 +20,18 @@
stored. If the table has any columns with potentially-wide values, stored. If the table has any columns with potentially-wide values,
there also might be a <acronym>TOAST</acronym> file associated with the table, there also might be a <acronym>TOAST</acronym> file associated with the table,
which is used to store values too wide to fit comfortably in the main which is used to store values too wide to fit comfortably in the main
table (see <xref linkend="storage-toast">). There will be one valid index table (see <xref linkend="storage-toast"/>). There will be one valid index
on the <acronym>TOAST</acronym> table, if present. There also might be indexes on the <acronym>TOAST</acronym> table, if present. There also might be indexes
associated with the base table. Each table and index is stored in a associated with the base table. Each table and index is stored in a
separate disk file &mdash; possibly more than one file, if the file would separate disk file &mdash; possibly more than one file, if the file would
exceed one gigabyte. Naming conventions for these files are described exceed one gigabyte. Naming conventions for these files are described
in <xref linkend="storage-file-layout">. in <xref linkend="storage-file-layout"/>.
</para> </para>
<para> <para>
You can monitor disk space in three ways: You can monitor disk space in three ways:
using the SQL functions listed in <xref linkend="functions-admin-dbsize">, using the SQL functions listed in <xref linkend="functions-admin-dbsize"/>,
using the <xref linkend="oid2name"> module, or using the <xref linkend="oid2name"/> module, or
using manual inspection of the system catalogs. using manual inspection of the system catalogs.
The SQL functions are the easiest to use and are generally recommended. The SQL functions are the easiest to use and are generally recommended.
The remainder of this section shows how to do it by inspection of the The remainder of this section shows how to do it by inspection of the
@ -124,7 +124,7 @@ ORDER BY relpages DESC;
If you cannot free up additional space on the disk by deleting If you cannot free up additional space on the disk by deleting
other things, you can move some of the database files to other file other things, you can move some of the database files to other file
systems by making use of tablespaces. See <xref systems by making use of tablespaces. See <xref
linkend="manage-ag-tablespaces"> for more information about that. linkend="manage-ag-tablespaces"/> for more information about that.
</para> </para>
<tip> <tip>

24
doc/src/sgml/dml.sgml
View File

@ -33,10 +33,10 @@
</para> </para>
<para> <para>
To create a new row, use the <xref linkend="sql-insert"> To create a new row, use the <xref linkend="sql-insert"/>
command. The command requires the command. The command requires the
table name and column values. For table name and column values. For
example, consider the products table from <xref linkend="ddl">: example, consider the products table from <xref linkend="ddl"/>:
<programlisting> <programlisting>
CREATE TABLE products ( CREATE TABLE products (
product_no integer, product_no integer,
@ -107,16 +107,16 @@ INSERT INTO products (product_no, name, price)
WHERE release_date = 'today'; WHERE release_date = 'today';
</programlisting> </programlisting>
This provides the full power of the SQL query mechanism (<xref This provides the full power of the SQL query mechanism (<xref
linkend="queries">) for computing the rows to be inserted. linkend="queries"/>) for computing the rows to be inserted.
</para> </para>
<tip> <tip>
<para> <para>
When inserting a lot of data at the same time, considering using When inserting a lot of data at the same time, considering using
the <xref linkend="sql-copy"> command. the <xref linkend="sql-copy"/> command.
It is not as flexible as the <xref linkend="sql-insert"> It is not as flexible as the <xref linkend="sql-insert"/>
command, but is more efficient. Refer command, but is more efficient. Refer
to <xref linkend="populate"> for more information on improving to <xref linkend="populate"/> for more information on improving
bulk loading performance. bulk loading performance.
</para> </para>
</tip> </tip>
@ -141,7 +141,7 @@ INSERT INTO products (product_no, name, price)
</para> </para>
<para> <para>
To update existing rows, use the <xref linkend="sql-update"> To update existing rows, use the <xref linkend="sql-update"/>
command. This requires command. This requires
three pieces of information: three pieces of information:
<orderedlist spacing="compact"> <orderedlist spacing="compact">
@ -160,7 +160,7 @@ INSERT INTO products (product_no, name, price)
</para> </para>
<para> <para>
Recall from <xref linkend="ddl"> that SQL does not, in general, Recall from <xref linkend="ddl"/> that SQL does not, in general,
provide a unique identifier for rows. Therefore it is not provide a unique identifier for rows. Therefore it is not
always possible to directly specify which row to update. always possible to directly specify which row to update.
Instead, you specify which conditions a row must meet in order to Instead, you specify which conditions a row must meet in order to
@ -203,7 +203,7 @@ UPDATE products SET price = price * 1.10;
this does not create any ambiguity. Of course, the this does not create any ambiguity. Of course, the
<literal>WHERE</literal> condition does <literal>WHERE</literal> condition does
not have to be an equality test. Many other operators are not have to be an equality test. Many other operators are
available (see <xref linkend="functions">). But the expression available (see <xref linkend="functions"/>). But the expression
needs to evaluate to a Boolean result. needs to evaluate to a Boolean result.
</para> </para>
@ -243,7 +243,7 @@ UPDATE mytable SET a = 5, b = 3, c = 1 WHERE a &gt; 0;
</para> </para>
<para> <para>
You use the <xref linkend="sql-delete"> You use the <xref linkend="sql-delete"/>
command to remove rows; the syntax is very similar to the command to remove rows; the syntax is very similar to the
<command>UPDATE</command> command. For instance, to remove all <command>UPDATE</command> command. For instance, to remove all
rows from the products table that have a price of 10, use: rows from the products table that have a price of 10, use:
@ -296,7 +296,7 @@ DELETE FROM products;
<para> <para>
The allowed contents of a <literal>RETURNING</literal> clause are the same as The allowed contents of a <literal>RETURNING</literal> clause are the same as
a <command>SELECT</command> command's output list a <command>SELECT</command> command's output list
(see <xref linkend="queries-select-lists">). It can contain column (see <xref linkend="queries-select-lists"/>). It can contain column
names of the command's target table, or value expressions using those names of the command's target table, or value expressions using those
columns. A common shorthand is <literal>RETURNING *</literal>, which selects columns. A common shorthand is <literal>RETURNING *</literal>, which selects
all columns of the target table in order. all columns of the target table in order.
@ -340,7 +340,7 @@ DELETE FROM products
</para> </para>
<para> <para>
If there are triggers (<xref linkend="triggers">) on the target table, If there are triggers (<xref linkend="triggers"/>) on the target table,
the data available to <literal>RETURNING</literal> is the row as modified by the data available to <literal>RETURNING</literal> is the row as modified by
the triggers. Thus, inspecting columns computed by triggers is another the triggers. Thus, inspecting columns computed by triggers is another
common use-case for <literal>RETURNING</literal>. common use-case for <literal>RETURNING</literal>.

219
doc/src/sgml/docguide.sgml
View File

@ -47,23 +47,11 @@
<para> <para>
The documentation sources are written in The documentation sources are written in
<firstterm>DocBook</firstterm>, which is a markup language <firstterm>DocBook</firstterm>, which is a markup language
superficially similar to <acronym>HTML</acronym>. Both of these defined in <acronym>XML</acronym>. In what
languages are applications of the <firstterm>Standard Generalized follows, the terms DocBook and <acronym>XML</acronym> are both
Markup Language</firstterm>, <acronym>SGML</acronym>, which is
essentially a language for describing other languages. In what
follows, the terms DocBook and <acronym>SGML</acronym> are both
used, but technically they are not interchangeable. used, but technically they are not interchangeable.
</para> </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> <para>
<productname>DocBook</productname> allows an author to specify the <productname>DocBook</productname> allows an author to specify the
structure and content of a technical document without worrying structure and content of a technical document without worrying
@ -97,19 +85,8 @@
<para> <para>
This is the definition of DocBook itself. We currently use version This is the definition of DocBook itself. We currently use version
4.2; you cannot use later or earlier versions. You need 4.2; you cannot use later or earlier versions. You need
the <acronym>SGML</acronym> and the <acronym>XML</acronym> variant of the <acronym>XML</acronym> variant of the DocBook DTD, not
the DocBook DTD of the same version. These will usually be in separate the <acronym>SGML</acronym> variant.
packages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879 character entities</ulink></term>
<listitem>
<para>
These are required by DocBook SGML but are distributed separately
because they are maintained by ISO.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -130,17 +107,6 @@
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term><ulink url="http://openjade.sourceforge.net">OpenSP</ulink></term>
<listitem>
<para>
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>
<varlistentry> <varlistentry>
<term><ulink url="http://xmlsoft.org/">Libxml2</ulink> for <command>xmllint</command></term> <term><ulink url="http://xmlsoft.org/">Libxml2</ulink> for <command>xmllint</command></term>
<listitem> <listitem>
@ -201,7 +167,7 @@
<para> <para>
To install the required packages, use: To install the required packages, use:
<programlisting> <programlisting>
yum install docbook-dtds docbook-style-xsl fop libxslt opensp yum install docbook-dtds docbook-style-xsl fop libxslt
</programlisting> </programlisting>
</para> </para>
</sect2> </sect2>
@ -209,41 +175,10 @@ yum install docbook-dtds docbook-style-xsl fop libxslt opensp
<sect2> <sect2>
<title>Installation on FreeBSD</title> <title>Installation on FreeBSD</title>
<para>
The FreeBSD Documentation Project is itself a heavy user of
DocBook, so it comes as no surprise that there is a full set of
<quote>ports</quote> of the documentation tools available on
FreeBSD. The following ports need to be installed to build the
documentation on FreeBSD.
<itemizedlist>
<listitem>
<para><filename>textproc/docbook-sgml</filename></para>
</listitem>
<listitem>
<para><filename>textproc/docbook-xml</filename></para>
</listitem>
<listitem>
<para><filename>textproc/docbook-xsl</filename></para>
</listitem>
<listitem>
<para><filename>textproc/dsssl-docbook-modular</filename></para>
</listitem>
<listitem>
<para><filename>textproc/libxslt</filename></para>
</listitem>
<listitem>
<para><filename>textproc/fop</filename></para>
</listitem>
<listitem>
<para><filename>textproc/opensp</filename></para>
</listitem>
</itemizedlist>
</para>
<para> <para>
To install the required packages with <command>pkg</command>, use: To install the required packages with <command>pkg</command>, use:
<programlisting> <programlisting>
pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp pkg install docbook-xml docbook-xsl fop libxslt
</programlisting> </programlisting>
</para> </para>
@ -268,7 +203,7 @@ pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp
available for <productname>Debian GNU/Linux</productname>. available for <productname>Debian GNU/Linux</productname>.
To install, simply use: To install, simply use:
<programlisting> <programlisting>
apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc apt-get install docbook-xml docbook-xsl fop libxml2-utils xsltproc
</programlisting> </programlisting>
</para> </para>
</sect2> </sect2>
@ -276,118 +211,22 @@ apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltpro
<sect2> <sect2>
<title>macOS</title> <title>macOS</title>
<para>
On macOS, you can build the HTML and man documentation without installing
anything extra. If you want to build PDFs or want to install a local copy
of DocBook, you can get those from your preferred package manager.
</para>
<para> <para>
If you use MacPorts, the following will get you set up: If you use MacPorts, the following will get you set up:
<programlisting> <programlisting>
sudo port install docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl fop libxslt opensp sudo port install docbook-xml-4.2 docbook-xsl fop
</programlisting> </programlisting>
</para> If you use Homebrew, use this:
</sect2>
<sect2>
<title>Manual Installation from Source</title>
<para>
The manual installation process of the DocBook tools is somewhat
complex, so if you have pre-built packages available, use them.
We describe here only a standard setup, with reasonably standard
installation paths, and no <quote>fancy</quote> features. For
details, you should study the documentation of the respective
package, and read <acronym>SGML</acronym> introductory material.
</para>
<sect3>
<title>Installing OpenSP</title>
<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/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 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>
<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
<procedure>
<step>
<para>
Obtain the <ulink url="http://www.docbook.org/sgml/4.2/docbook-4.2.zip">
DocBook V4.2 distribution</ulink>.
</para>
</step>
<step>
<para>
Create the directory
<filename>/usr/local/share/sgml/docbook-4.2</filename> and change
to it. (The exact location is irrelevant, but this one is
reasonable within the layout we are following here.)
<screen>
<prompt>$ </prompt><userinput>mkdir /usr/local/share/sgml/docbook-4.2</userinput>
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
</screen>
</para>
</step>
<step>
<para>
Unpack the archive:
<screen>
<prompt>$ </prompt><userinput>unzip -a ...../docbook-4.2.zip</userinput>
</screen>
(The archive will unpack its files into the current directory.)
</para>
</step>
<step>
<para>
Edit the file
<filename>/usr/local/share/sgml/catalog</filename> (or whatever
you told jade during installation) and put a line like this
into it:
<programlisting> <programlisting>
CATALOG "docbook-4.2/docbook.cat" brew install docbook docbook-xsl fop
</programlisting> </programlisting>
</para> </para>
</step>
<step>
<para>
Download the <ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">
ISO 8879 character entities archive</ulink>, unpack it, and put the
files in the same directory you put the DocBook files in:
<screen>
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
<prompt>$ </prompt><userinput>unzip ...../ISOEnts.zip</userinput>
</screen>
</para>
</step>
<step>
<para>
Run the following command in the directory with the DocBook and ISO files:
<programlisting>
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
</programlisting>
(This fixes a mixup between the names used in the DocBook
catalog file and the actual names of the ISO character entity
files.)
</para>
</step>
</procedure>
</sect3>
</sect2> </sect2>
<sect2 id="docguide-toolsets-configure"> <sect2 id="docguide-toolsets-configure">
@ -400,26 +239,14 @@ perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
Check the output near the end of the run, it should look something Check the output near the end of the run, it should look something
like this: like this:
<screen> <screen>
<computeroutput>
checking for onsgmls... onsgmls
checking for DocBook V4.2... yes
checking for dbtoepub... dbtoepub
checking for xmllint... xmllint checking for xmllint... xmllint
checking for DocBook XML V4.2... yes
checking for dbtoepub... dbtoepub
checking for xsltproc... xsltproc checking for xsltproc... xsltproc
checking for osx... osx
checking for fop... fop checking for fop... fop
</computeroutput>
</screen> </screen>
If neither <filename>onsgmls</filename> nor If <filename>xmllint</filename> was not found then some of the following
<filename>nsgmls</filename> were found then some of the following tests tests will be skipped.
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 OpenSP can find it, or you have
not set up the catalog files correctly. See the installation hints
above.
</para> </para>
</sect2> </sect2>
@ -464,9 +291,7 @@ checking for fop... fop
We use the DocBook XSL stylesheets to We use the DocBook XSL stylesheets to
convert <productname>DocBook</productname> convert <productname>DocBook</productname>
<sgmltag>refentry</sgmltag> pages to *roff output suitable for man <sgmltag>refentry</sgmltag> pages to *roff output suitable for man
pages. The man pages are also distributed as a tar archive, pages. To create the man pages, use the command:
similar to the <acronym>HTML</acronym> version. To create the man
pages, use the commands:
<screen> <screen>
<prompt>doc/src/sgml$ </prompt><userinput>make man</userinput> <prompt>doc/src/sgml$ </prompt><userinput>make man</userinput>
</screen> </screen>
@ -536,7 +361,7 @@ ADDITIONAL_FLAGS='-Xmx1000m'
The installation instructions are also distributed as plain text, The installation instructions are also distributed as plain text,
in case they are needed in a situation where better reading tools in case they are needed in a situation where better reading tools
are not available. The <filename>INSTALL</filename> file are not available. The <filename>INSTALL</filename> file
corresponds to <xref linkend="installation">, with some minor corresponds to <xref linkend="installation"/>, with some minor
changes to account for the different context. To recreate the changes to account for the different context. To recreate the
file, change to the directory <filename>doc/src/sgml</filename> file, change to the directory <filename>doc/src/sgml</filename>
and enter <userinput>make INSTALL</userinput>. and enter <userinput>make INSTALL</userinput>.

4
doc/src/sgml/earthdistance.sgml
View File

@ -56,7 +56,7 @@
<para> <para>
The provided functions are shown The provided functions are shown
in <xref linkend="earthdistance-cube-functions">. in <xref linkend="earthdistance-cube-functions"/>.
</para> </para>
<table id="earthdistance-cube-functions"> <table id="earthdistance-cube-functions">
@ -150,7 +150,7 @@
<para> <para>
A single operator is provided, shown A single operator is provided, shown
in <xref linkend="earthdistance-point-operators">. in <xref linkend="earthdistance-point-operators"/>.
</para> </para>
<table id="earthdistance-point-operators"> <table id="earthdistance-point-operators">

192
doc/src/sgml/ecpg.sgml
View File

@ -31,7 +31,7 @@
specially marked sections. To build the program, the source code (<filename>*.pgc</filename>) specially marked sections. To build the program, the source code (<filename>*.pgc</filename>)
is first passed through the embedded SQL preprocessor, which converts it is first passed through the embedded SQL preprocessor, which converts it
to an ordinary C program (<filename>*.c</filename>), and afterwards it can be processed by a C to an ordinary C program (<filename>*.c</filename>), and afterwards it can be processed by a C
compiler. (For details about the compiling and linking see <xref linkend="ecpg-process">). compiler. (For details about the compiling and linking see <xref linkend="ecpg-process"/>).
Converted ECPG applications call functions in the libpq library Converted ECPG applications call functions in the libpq library
through the embedded SQL library (ecpglib), and communicate with through the embedded SQL library (ecpglib), and communicate with
the PostgreSQL server using the normal frontend-backend protocol. the PostgreSQL server using the normal frontend-backend protocol.
@ -397,9 +397,9 @@ EXEC SQL COMMIT;
row can also be executed using row can also be executed using
<literal>EXEC SQL</literal> directly. To handle result sets with <literal>EXEC SQL</literal> directly. To handle result sets with
multiple rows, an application has to use a cursor; multiple rows, an application has to use a cursor;
see <xref linkend="ecpg-cursors"> below. (As a special case, an see <xref linkend="ecpg-cursors"/> below. (As a special case, an
application can fetch multiple rows at once into an array host application can fetch multiple rows at once into an array host
variable; see <xref linkend="ecpg-variables-arrays">.) variable; see <xref linkend="ecpg-variables-arrays"/>.)
</para> </para>
<para> <para>
@ -422,7 +422,7 @@ EXEC SQL SHOW search_path INTO :var;
<literal>:<replaceable>something</replaceable></literal> are <literal>:<replaceable>something</replaceable></literal> are
<firstterm>host variables</firstterm>, that is, they refer to <firstterm>host variables</firstterm>, that is, they refer to
variables in the C program. They are explained in <xref variables in the C program. They are explained in <xref
linkend="ecpg-variables">. linkend="ecpg-variables"/>.
</para> </para>
</sect2> </sect2>
@ -452,8 +452,8 @@ EXEC SQL COMMIT;
<para> <para>
For more details about declaration of the cursor, For more details about declaration of the cursor,
see <xref linkend="ecpg-sql-declare">, and see <xref linkend="ecpg-sql-declare"/>, and
see <xref linkend="sql-fetch"> for <literal>FETCH</literal> command see <xref linkend="sql-fetch"/> for <literal>FETCH</literal> command
details. details.
</para> </para>
@ -477,7 +477,7 @@ EXEC SQL COMMIT;
interface also supports autocommit of transactions (similar to interface also supports autocommit of transactions (similar to
<application>psql</application>'s default behavior) via the <option>-t</option> <application>psql</application>'s default behavior) via the <option>-t</option>
command-line option to <command>ecpg</command> (see <xref command-line option to <command>ecpg</command> (see <xref
linkend="app-ecpg">) or via the <literal>EXEC SQL SET AUTOCOMMIT TO linkend="app-ecpg"/>) or via the <literal>EXEC SQL SET AUTOCOMMIT TO
ON</literal> statement. In autocommit mode, each command is ON</literal> statement. In autocommit mode, each command is
automatically committed unless it is inside an explicit transaction automatically committed unless it is inside an explicit transaction
block. This mode can be explicitly turned off using <literal>EXEC block. This mode can be explicitly turned off using <literal>EXEC
@ -617,8 +617,8 @@ EXEC SQL DEALLOCATE PREPARE <replaceable>name</replaceable>;
<para> <para>
For more details about <literal>PREPARE</literal>, For more details about <literal>PREPARE</literal>,
see <xref linkend="ecpg-sql-prepare">. Also see <xref linkend="ecpg-sql-prepare"/>. Also
see <xref linkend="ecpg-dynamic"> for more details about using see <xref linkend="ecpg-dynamic"/> for more details about using
placeholders and input parameters. placeholders and input parameters.
</para> </para>
</sect2> </sect2>
@ -628,7 +628,7 @@ EXEC SQL DEALLOCATE PREPARE <replaceable>name</replaceable>;
<title>Using Host Variables</title> <title>Using Host Variables</title>
<para> <para>
In <xref linkend="ecpg-commands"> you saw how you can execute SQL In <xref linkend="ecpg-commands"/> you saw how you can execute SQL
statements from an embedded SQL program. Some of those statements statements from an embedded SQL program. Some of those statements
only used fixed values and did not provide a way to insert only used fixed values and did not provide a way to insert
user-supplied values into statements or have the program process user-supplied values into statements or have the program process
@ -646,7 +646,7 @@ EXEC SQL DEALLOCATE PREPARE <replaceable>name</replaceable>;
<para> <para>
Another way to exchange values between PostgreSQL backends and ECPG Another way to exchange values between PostgreSQL backends and ECPG
applications is the use of SQL descriptors, described applications is the use of SQL descriptors, described
in <xref linkend="ecpg-descriptors">. in <xref linkend="ecpg-descriptors"/>.
</para> </para>
<sect2 id="ecpg-variables-overview"> <sect2 id="ecpg-variables-overview">
@ -812,11 +812,11 @@ do
directly. Other PostgreSQL data types, such directly. Other PostgreSQL data types, such
as <type>timestamp</type> and <type>numeric</type> can only be as <type>timestamp</type> and <type>numeric</type> can only be
accessed through special library functions; see accessed through special library functions; see
<xref linkend="ecpg-special-types">. <xref linkend="ecpg-special-types"/>.
</para> </para>
<para> <para>
<xref linkend="ecpg-datatype-hostvars-table"> shows which PostgreSQL <xref linkend="ecpg-datatype-hostvars-table"/> shows which PostgreSQL
data types correspond to which C data types. When you wish to data types correspond to which C data types. When you wish to
send or receive a value of a given PostgreSQL data type, you send or receive a value of a given PostgreSQL data type, you
should declare a C variable of the corresponding C data type in should declare a C variable of the corresponding C data type in
@ -851,12 +851,12 @@ do
<row> <row>
<entry><type>decimal</type></entry> <entry><type>decimal</type></entry>
<entry><type>decimal</type><footnote id="ecpg-datatype-table-fn"><para>This type can only be accessed through special library functions; see <xref linkend="ecpg-special-types">.</para></footnote></entry> <entry><type>decimal</type><footnote id="ecpg-datatype-table-fn"><para>This type can only be accessed through special library functions; see <xref linkend="ecpg-special-types"/>.</para></footnote></entry>
</row> </row>
<row> <row>
<entry><type>numeric</type></entry> <entry><type>numeric</type></entry>
<entry><type>numeric</type><footnoteref linkend="ecpg-datatype-table-fn"></entry> <entry><type>numeric</type><footnoteref linkend="ecpg-datatype-table-fn"/></entry>
</row> </row>
<row> <row>
@ -901,17 +901,17 @@ do
<row> <row>
<entry><type>timestamp</type></entry> <entry><type>timestamp</type></entry>
<entry><type>timestamp</type><footnoteref linkend="ecpg-datatype-table-fn"></entry> <entry><type>timestamp</type><footnoteref linkend="ecpg-datatype-table-fn"/></entry>
</row> </row>
<row> <row>
<entry><type>interval</type></entry> <entry><type>interval</type></entry>
<entry><type>interval</type><footnoteref linkend="ecpg-datatype-table-fn"></entry> <entry><type>interval</type><footnoteref linkend="ecpg-datatype-table-fn"/></entry>
</row> </row>
<row> <row>
<entry><type>date</type></entry> <entry><type>date</type></entry>
<entry><type>date</type><footnoteref linkend="ecpg-datatype-table-fn"></entry> <entry><type>date</type><footnoteref linkend="ecpg-datatype-table-fn"/></entry>
</row> </row>
<row> <row>
@ -1002,7 +1002,7 @@ struct varchar_var { int len; char arr[180]; } var;
structure. Applications deal with these types by declaring host structure. Applications deal with these types by declaring host
variables in special types and accessing them using functions in variables in special types and accessing them using functions in
the pgtypes library. The pgtypes library, described in detail the pgtypes library. The pgtypes library, described in detail
in <xref linkend="ecpg-pgtypes"> contains basic functions to deal in <xref linkend="ecpg-pgtypes"/> contains basic functions to deal
with those types, such that you do not need to send a query to with those types, such that you do not need to send a query to
the SQL server just for adding an interval to a time stamp for the SQL server just for adding an interval to a time stamp for
example. example.
@ -1011,7 +1011,7 @@ struct varchar_var { int len; char arr[180]; } var;
<para> <para>
The follow subsections describe these special data types. For The follow subsections describe these special data types. For
more details about pgtypes library functions, more details about pgtypes library functions,
see <xref linkend="ecpg-pgtypes">. see <xref linkend="ecpg-pgtypes"/>.
</para> </para>
<sect4> <sect4>
@ -1062,7 +1062,7 @@ ts = 2010-06-27 18:03:56.949343
program has to include <filename>pgtypes_date.h</filename>, declare a host variable program has to include <filename>pgtypes_date.h</filename>, declare a host variable
as the date type and convert a DATE value into a text form using as the date type and convert a DATE value into a text form using
<function>PGTYPESdate_to_asc()</function> function. For more details about the <function>PGTYPESdate_to_asc()</function> function. For more details about the
pgtypes library functions, see <xref linkend="ecpg-pgtypes">. pgtypes library functions, see <xref linkend="ecpg-pgtypes"/>.
</para> </para>
</sect4> </sect4>
@ -1117,7 +1117,7 @@ EXEC SQL END DECLARE SECTION;
allocating some memory space on the heap, and accessing the allocating some memory space on the heap, and accessing the
variable using the pgtypes library functions. For more details variable using the pgtypes library functions. For more details
about the pgtypes library functions, about the pgtypes library functions,
see <xref linkend="ecpg-pgtypes">. see <xref linkend="ecpg-pgtypes"/>.
</para> </para>
<para> <para>
@ -1193,7 +1193,7 @@ EXEC SQL END DECLARE SECTION;
There are two use cases for arrays as host variables. The first There are two use cases for arrays as host variables. The first
is a way to store some text string in <type>char[]</type> is a way to store some text string in <type>char[]</type>
or <type>VARCHAR[]</type>, as or <type>VARCHAR[]</type>, as
explained in <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 retrieve multiple rows from a query result without using a
cursor. Without an array, to process a query result consisting cursor. Without an array, to process a query result consisting
of multiple rows, it is required to use a cursor and of multiple rows, it is required to use a cursor and
@ -1378,7 +1378,7 @@ EXEC SQL TYPE serial_t IS long;
<para> <para>
You can declare pointers to the most common types. Note however You can declare pointers to the most common types. Note however
that you cannot use pointers as target variables of queries that you cannot use pointers as target variables of queries
without auto-allocation. See <xref linkend="ecpg-descriptors"> without auto-allocation. See <xref linkend="ecpg-descriptors"/>
for more information on auto-allocation. for more information on auto-allocation.
</para> </para>
@ -1520,7 +1520,7 @@ while (1)
Another workaround is to store arrays in their external string Another workaround is to store arrays in their external string
representation in host variables of type <type>char[]</type> representation in host variables of type <type>char[]</type>
or <type>VARCHAR[]</type>. For more details about this or <type>VARCHAR[]</type>. For more details about this
representation, see <xref linkend="arrays-input">. Note that representation, see <xref linkend="arrays-input"/>. Note that
this means that the array cannot be accessed naturally as an this means that the array cannot be accessed naturally as an
array in the host program (without further processing that parses array in the host program (without further processing that parses
the text representation). the text representation).
@ -1578,7 +1578,7 @@ EXEC SQL CLOSE cur1;
To enhance this example, the host variables to store values in To enhance this example, the host variables to store values in
the <command>FETCH</command> command can be gathered into one the <command>FETCH</command> command can be gathered into one
structure. For more details about the host variable in the structure. For more details about the host variable in the
structure form, see <xref linkend="ecpg-variables-struct">. structure form, see <xref linkend="ecpg-variables-struct"/>.
To switch to the structure, the example can be modified as below. To switch to the structure, the example can be modified as below.
The two host variables, <varname>intval</varname> The two host variables, <varname>intval</varname>
and <varname>textval</varname>, become members of and <varname>textval</varname>, become members of
@ -1659,12 +1659,12 @@ while (1)
<para> <para>
Here is an example using the data type <type>complex</type> from Here is an example using the data type <type>complex</type> from
the example in <xref linkend="xtypes">. The external string the example in <xref linkend="xtypes"/>. The external string
representation of that type is <literal>(%lf,%lf)</literal>, representation of that type is <literal>(%lf,%lf)</literal>,
which is defined in the which is defined in the
functions <function>complex_in()</function> functions <function>complex_in()</function>
and <function>complex_out()</function> functions and <function>complex_out()</function> functions
in <xref linkend="xtypes">. The following example inserts the in <xref linkend="xtypes"/>. The following example inserts the
complex type values <literal>(1,1)</literal> complex type values <literal>(1,1)</literal>
and <literal>(3,3)</literal> into the and <literal>(3,3)</literal> into the
columns <literal>a</literal> and <literal>b</literal>, and select columns <literal>a</literal> and <literal>b</literal>, and select
@ -1875,7 +1875,7 @@ EXEC SQL EXECUTE mystmt INTO :v1, :v2, :v3 USING 37;
<para> <para>
If a query is expected to return more than one result row, a If a query is expected to return more than one result row, a
cursor should be used, as in the following example. cursor should be used, as in the following example.
(See <xref linkend="ecpg-cursors"> for more details about the (See <xref linkend="ecpg-cursors"/> for more details about the
cursor.) cursor.)
<programlisting> <programlisting>
EXEC SQL BEGIN DECLARE SECTION; EXEC SQL BEGIN DECLARE SECTION;
@ -1941,7 +1941,7 @@ free(out);
<title>The numeric Type</title> <title>The numeric Type</title>
<para> <para>
The numeric type offers to do calculations with arbitrary precision. See The numeric type offers to do calculations with arbitrary precision. See
<xref linkend="datatype-numeric"> for the equivalent type in the <xref linkend="datatype-numeric"/> for the equivalent type in the
<productname>PostgreSQL</productname> server. Because of the arbitrary precision this <productname>PostgreSQL</productname> server. Because of the arbitrary precision this
variable needs to be able to expand and shrink dynamically. That's why you variable needs to be able to expand and shrink dynamically. That's why you
can only create numeric variables on the heap, by means of the can only create numeric variables on the heap, by means of the
@ -2264,7 +2264,7 @@ int PGTYPESnumeric_from_decimal(decimal *src, numeric *dst);
<title>The date Type</title> <title>The date Type</title>
<para> <para>
The date type in C enables your programs to deal with data of the SQL type The date type in C enables your programs to deal with data of the SQL type
date. See <xref linkend="datatype-datetime"> for the equivalent type in the date. See <xref linkend="datatype-datetime"/> for the equivalent type in the
<productname>PostgreSQL</productname> server. <productname>PostgreSQL</productname> server.
</para> </para>
<para> <para>
@ -2303,7 +2303,7 @@ date PGTYPESdate_from_asc(char *str, char **endptr);
currently no variable to change that within ECPG. currently no variable to change that within ECPG.
</para> </para>
<para> <para>
<xref linkend="ecpg-pgtypesdate-from-asc-table"> shows the allowed input formats. <xref linkend="ecpg-pgtypesdate-from-asc-table"/> shows the allowed input formats.
</para> </para>
<table id="ecpg-pgtypesdate-from-asc-table"> <table id="ecpg-pgtypesdate-from-asc-table">
<title>Valid Input Formats for <function>PGTYPESdate_from_asc</function></title> <title>Valid Input Formats for <function>PGTYPESdate_from_asc</function></title>
@ -2558,7 +2558,7 @@ int PGTYPESdate_fmt_asc(date dDate, char *fmtstring, char *outbuf);
All other characters are copied 1:1 to the output string. All other characters are copied 1:1 to the output string.
</para> </para>
<para> <para>
<xref linkend="ecpg-pgtypesdate-fmt-asc-example-table"> indicates a few possible formats. This will give <xref linkend="ecpg-pgtypesdate-fmt-asc-example-table"/> indicates a few possible formats. This will give
you an idea of how to use this function. All output lines are based on you an idea of how to use this function. All output lines are based on
the same date: November 23, 1959. the same date: November 23, 1959.
</para> </para>
@ -2649,7 +2649,7 @@ int PGTYPESdate_defmt_asc(date *d, char *fmt, char *str);
day. day.
</para> </para>
<para> <para>
<xref linkend="ecpg-rdefmtdate-example-table"> indicates a few possible formats. This will give <xref linkend="ecpg-rdefmtdate-example-table"/> indicates a few possible formats. This will give
you an idea of how to use this function. you an idea of how to use this function.
</para> </para>
<table id="ecpg-rdefmtdate-example-table"> <table id="ecpg-rdefmtdate-example-table">
@ -2741,7 +2741,7 @@ int PGTYPESdate_defmt_asc(date *d, char *fmt, char *str);
<title>The timestamp Type</title> <title>The timestamp Type</title>
<para> <para>
The timestamp type in C enables your programs to deal with data of the SQL The timestamp type in C enables your programs to deal with data of the SQL
type timestamp. See <xref linkend="datatype-datetime"> for the equivalent type timestamp. See <xref linkend="datatype-datetime"/> for the equivalent
type in the <productname>PostgreSQL</productname> server. type in the <productname>PostgreSQL</productname> server.
</para> </para>
<para> <para>
@ -2766,7 +2766,7 @@ timestamp PGTYPEStimestamp_from_asc(char *str, char **endptr);
<para> <para>
The function returns the parsed timestamp on success. On error, The function returns the parsed timestamp on success. On error,
<literal>PGTYPESInvalidTimestamp</literal> is returned and <varname>errno</varname> is <literal>PGTYPESInvalidTimestamp</literal> is returned and <varname>errno</varname> is
set to <literal>PGTYPES_TS_BAD_TIMESTAMP</literal>. See <xref linkend="pgtypesinvalidtimestamp"> for important notes on this value. set to <literal>PGTYPES_TS_BAD_TIMESTAMP</literal>. See <xref linkend="pgtypesinvalidtimestamp"/> for important notes on this value.
</para> </para>
<para> <para>
In general, the input string can contain any combination of an allowed In general, the input string can contain any combination of an allowed
@ -2777,7 +2777,7 @@ timestamp PGTYPEStimestamp_from_asc(char *str, char **endptr);
specifiers are silently discarded. specifiers are silently discarded.
</para> </para>
<para> <para>
<xref linkend="ecpg-pgtypestimestamp-from-asc-example-table"> contains a few examples for input strings. <xref linkend="ecpg-pgtypestimestamp-from-asc-example-table"/> contains a few examples for input strings.
</para> </para>
<table id="ecpg-pgtypestimestamp-from-asc-example-table"> <table id="ecpg-pgtypestimestamp-from-asc-example-table">
<title>Valid Input Formats for <function>PGTYPEStimestamp_from_asc</function></title> <title>Valid Input Formats for <function>PGTYPEStimestamp_from_asc</function></title>
@ -3217,7 +3217,7 @@ int PGTYPEStimestamp_defmt_asc(char *str, char *fmt, timestamp *d);
</para> </para>
<para> <para>
This is the reverse function to <xref This is the reverse function to <xref
linkend="pgtypestimestampfmtasc">. See the documentation there in linkend="pgtypestimestampfmtasc"/>. See the documentation there in
order to find out about the possible formatting mask entries. order to find out about the possible formatting mask entries.
</para> </para>
</listitem> </listitem>
@ -3270,7 +3270,7 @@ int PGTYPEStimestamp_sub_interval(timestamp *tin, interval *span, timestamp *tou
<title>The interval Type</title> <title>The interval Type</title>
<para> <para>
The interval type in C enables your programs to deal with data of the SQL The interval type in C enables your programs to deal with data of the SQL
type interval. See <xref linkend="datatype-datetime"> for the equivalent type interval. See <xref linkend="datatype-datetime"/> for the equivalent
type in the <productname>PostgreSQL</productname> server. type in the <productname>PostgreSQL</productname> server.
</para> </para>
<para> <para>
@ -3364,7 +3364,7 @@ int PGTYPESinterval_copy(interval *intvlsrc, interval *intvldest);
<function>PGTYPESdecimal_free</function>). <function>PGTYPESdecimal_free</function>).
There are a lot of other functions that deal with the decimal type in the There are a lot of other functions that deal with the decimal type in the
<productname>Informix</productname> compatibility mode described in <xref <productname>Informix</productname> compatibility mode described in <xref
linkend="ecpg-informix-compat">. linkend="ecpg-informix-compat"/>.
</para> </para>
<para> <para>
The following functions can be used to work with the decimal type and are The following functions can be used to work with the decimal type and are
@ -3632,7 +3632,7 @@ EXEC SQL DESCRIBE stmt1 INTO SQL DESCRIPTOR mydesc;
so using <literal>DESCRIPTOR</literal> and <literal>SQL DESCRIPTOR</literal> so using <literal>DESCRIPTOR</literal> and <literal>SQL DESCRIPTOR</literal>
produced named SQL Descriptor Areas. Now it is mandatory, omitting produced named SQL Descriptor Areas. Now it is mandatory, omitting
the <literal>SQL</literal> keyword produces SQLDA Descriptor Areas, the <literal>SQL</literal> keyword produces SQLDA Descriptor Areas,
see <xref linkend="ecpg-sqlda-descriptors">. see <xref linkend="ecpg-sqlda-descriptors"/>.
</para> </para>
<para> <para>
@ -3853,7 +3853,7 @@ EXEC SQL FETCH 3 FROM mycursor INTO DESCRIPTOR mysqlda;
</programlisting> </programlisting>
Note that the <literal>SQL</literal> keyword is omitted. The paragraphs about Note that the <literal>SQL</literal> keyword is omitted. The paragraphs about
the use cases of the <literal>INTO</literal> and <literal>USING</literal> the use cases of the <literal>INTO</literal> and <literal>USING</literal>
keywords in <xref linkend="ecpg-named-descriptors"> also apply here with an addition. keywords in <xref linkend="ecpg-named-descriptors"/> also apply here with an addition.
In a <command>DESCRIBE</command> statement the <literal>DESCRIPTOR</literal> In a <command>DESCRIBE</command> statement the <literal>DESCRIPTOR</literal>
keyword can be completely omitted if the <literal>INTO</literal> keyword is used: keyword can be completely omitted if the <literal>INTO</literal> keyword is used:
<programlisting> <programlisting>
@ -4038,7 +4038,7 @@ typedef struct sqlvar_struct sqlvar_t;
<listitem> <listitem>
<para> <para>
Points to the data. The format of the data is described Points to the data. The format of the data is described
in <xref linkend="ecpg-variables-type-mapping">. in <xref linkend="ecpg-variables-type-mapping"/>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -4447,7 +4447,7 @@ main(void)
<para> <para>
The whole program is shown The whole program is shown
in <xref linkend="ecpg-sqlda-example-example">. in <xref linkend="ecpg-sqlda-example-example"/>.
</para> </para>
<example id="ecpg-sqlda-example-example"> <example id="ecpg-sqlda-example-example">
@ -5016,7 +5016,7 @@ sqlstate: 42P01
<literal>SQLSTATE</literal> error codes; therefore a high degree <literal>SQLSTATE</literal> error codes; therefore a high degree
of consistency can be achieved by using this error code scheme of consistency can be achieved by using this error code scheme
throughout all applications. For further information see throughout all applications. For further information see
<xref linkend="errcodes-appendix">. <xref linkend="errcodes-appendix"/>.
</para> </para>
<para> <para>
@ -5037,7 +5037,7 @@ sqlstate: 42P01
<literal>SQLSTATE</literal> is also listed. There is, however, no <literal>SQLSTATE</literal> is also listed. There is, however, no
one-to-one or one-to-many mapping between the two schemes (indeed one-to-one or one-to-many mapping between the two schemes (indeed
it is many-to-many), so you should consult the global it is many-to-many), so you should consult the global
<literal>SQLSTATE</literal> listing in <xref linkend="errcodes-appendix"> <literal>SQLSTATE</literal> listing in <xref linkend="errcodes-appendix"/>
in each case. in each case.
</para> </para>
@ -5767,7 +5767,7 @@ ECPG = ecpg
<para> <para>
The complete syntax of the <command>ecpg</command> command is The complete syntax of the <command>ecpg</command> command is
detailed in <xref linkend="app-ecpg">. detailed in <xref linkend="app-ecpg"/>.
</para> </para>
<para> <para>
@ -5835,7 +5835,7 @@ ECPG = ecpg
<para> <para>
<function>ECPGtransactionStatus(const char *<replaceable>connection_name</replaceable>)</function> <function>ECPGtransactionStatus(const char *<replaceable>connection_name</replaceable>)</function>
returns the current transaction status of the given connection identified by <replaceable>connection_name</replaceable>. returns the current transaction status of the given connection identified by <replaceable>connection_name</replaceable>.
See <xref linkend="libpq-status"> and libpq's <function>PQtransactionStatus()</function> for details about the returned status codes. See <xref linkend="libpq-status"/> and libpq's <function>PQtransactionStatus()</function> for details about the returned status codes.
</para> </para>
</listitem> </listitem>
@ -5867,8 +5867,8 @@ ECPG = ecpg
<para> <para>
For more details about the <function>ECPGget_PGconn()</function>, see For more details about the <function>ECPGget_PGconn()</function>, see
<xref linkend="ecpg-library">. For information about the large <xref linkend="ecpg-library"/>. For information about the large
object function interface, see <xref linkend="largeobjects">. object function interface, see <xref linkend="largeobjects"/>.
</para> </para>
<para> <para>
@ -5878,7 +5878,7 @@ ECPG = ecpg
</para> </para>
<para> <para>
<xref linkend="ecpg-lo-example"> shows an example program that <xref linkend="ecpg-lo-example"/> shows an example program that
illustrates how to create, write, and read a large object in an illustrates how to create, write, and read a large object in an
ECPG application. ECPG application.
</para> </para>
@ -5997,7 +5997,7 @@ main(void)
A safe way to use the embedded SQL code in a C++ application is A safe way to use the embedded SQL code in a C++ application is
hiding the ECPG calls in a C module, which the C++ application code hiding the ECPG calls in a C module, which the C++ application code
calls into to access the database, and linking that together with calls into to access the database, and linking that together with
the rest of the C++ code. See <xref linkend="ecpg-cpp-and-c"> the rest of the C++ code. See <xref linkend="ecpg-cpp-and-c"/>
about that. about that.
</para> </para>
@ -6252,7 +6252,7 @@ c++ test_cpp.o test_mod.o -lecpg -o test_cpp
<para> <para>
This section describes all SQL commands that are specific to This section describes all SQL commands that are specific to
embedded SQL. Also refer to the SQL commands listed embedded SQL. Also refer to the SQL commands listed
in <xref linkend="sql-commands">, which can also be used in in <xref linkend="sql-commands"/>, which can also be used in
embedded SQL, unless stated otherwise. embedded SQL, unless stated otherwise.
</para> </para>
@ -6320,9 +6320,9 @@ EXEC SQL ALLOCATE DESCRIPTOR mydesc;
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="ecpg-sql-deallocate-descriptor"></member> <member><xref linkend="ecpg-sql-deallocate-descriptor"/></member>
<member><xref linkend="ecpg-sql-get-descriptor"></member> <member><xref linkend="ecpg-sql-get-descriptor"/></member>
<member><xref linkend="ecpg-sql-set-descriptor"></member> <member><xref linkend="ecpg-sql-set-descriptor"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>
@ -6539,8 +6539,8 @@ EXEC SQL END DECLARE SECTION;
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="ecpg-sql-disconnect"></member> <member><xref linkend="ecpg-sql-disconnect"/></member>
<member><xref linkend="ecpg-sql-set-connection"></member> <member><xref linkend="ecpg-sql-set-connection"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>
@ -6604,9 +6604,9 @@ EXEC SQL DEALLOCATE DESCRIPTOR mydesc;
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="ecpg-sql-allocate-descriptor"></member> <member><xref linkend="ecpg-sql-allocate-descriptor"/></member>
<member><xref linkend="ecpg-sql-get-descriptor"></member> <member><xref linkend="ecpg-sql-get-descriptor"/></member>
<member><xref linkend="ecpg-sql-set-descriptor"></member> <member><xref linkend="ecpg-sql-set-descriptor"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>
@ -6668,8 +6668,8 @@ DECLARE <replaceable class="parameter">cursor_name</replaceable> [ BINARY ] [ IN
<term><replaceable class="parameter">query</replaceable></term> <term><replaceable class="parameter">query</replaceable></term>
<listitem> <listitem>
<para> <para>
A <xref linkend="sql-select"> or A <xref linkend="sql-select"/> or
<xref linkend="sql-values"> command which will provide the <xref linkend="sql-values"/> command which will provide the
rows to be returned by the cursor. rows to be returned by the cursor.
</para> </para>
</listitem> </listitem>
@ -6678,7 +6678,7 @@ DECLARE <replaceable class="parameter">cursor_name</replaceable> [ BINARY ] [ IN
<para> <para>
For the meaning of the cursor options, For the meaning of the cursor options,
see <xref linkend="sql-declare">. see <xref linkend="sql-declare"/>.
</para> </para>
</refsect1> </refsect1>
@ -6715,9 +6715,9 @@ EXEC SQL DECLARE cur1 CURSOR FOR stmt1;
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="ecpg-sql-open"></member> <member><xref linkend="ecpg-sql-open"/></member>
<member><xref linkend="sql-close"></member> <member><xref linkend="sql-close"/></member>
<member><xref linkend="sql-declare"></member> <member><xref linkend="sql-declare"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>
@ -6805,8 +6805,8 @@ EXEC SQL DEALLOCATE DESCRIPTOR mydesc;
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="ecpg-sql-allocate-descriptor"></member> <member><xref linkend="ecpg-sql-allocate-descriptor"/></member>
<member><xref linkend="ecpg-sql-get-descriptor"></member> <member><xref linkend="ecpg-sql-get-descriptor"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>
@ -6915,8 +6915,8 @@ main(void)
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="ecpg-sql-connect"></member> <member><xref linkend="ecpg-sql-connect"/></member>
<member><xref linkend="ecpg-sql-set-connection"></member> <member><xref linkend="ecpg-sql-set-connection"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>
@ -7056,7 +7056,7 @@ GET DESCRIPTOR <replaceable class="parameter">descriptor_name</replaceable> VALU
<listitem> <listitem>
<para> <para>
A token identifying which item of information about a column A token identifying which item of information about a column
to retrieve. See <xref linkend="ecpg-named-descriptors"> for to retrieve. See <xref linkend="ecpg-named-descriptors"/> for
a list of supported items. a list of supported items.
</para> </para>
</listitem> </listitem>
@ -7164,8 +7164,8 @@ d_data = testdb
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="ecpg-sql-allocate-descriptor"></member> <member><xref linkend="ecpg-sql-allocate-descriptor"/></member>
<member><xref linkend="ecpg-sql-set-descriptor"></member> <member><xref linkend="ecpg-sql-set-descriptor"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>
@ -7258,8 +7258,8 @@ EXEC SQL OPEN :curname1;
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="ecpg-sql-declare"></member> <member><xref linkend="ecpg-sql-declare"/></member>
<member><xref linkend="sql-close"></member> <member><xref linkend="sql-close"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>
@ -7282,8 +7282,8 @@ PREPARE <replaceable class="parameter">name</replaceable> FROM <replaceable clas
<para> <para>
<command>PREPARE</command> prepares a statement dynamically <command>PREPARE</command> prepares a statement dynamically
specified as a string for execution. This is different from the specified as a string for execution. This is different from the
direct SQL statement <xref linkend="sql-prepare">, which can also direct SQL statement <xref linkend="sql-prepare"/>, which can also
be used in embedded programs. The <xref linkend="sql-execute"> be used in embedded programs. The <xref linkend="sql-execute"/>
command is used to execute either kind of prepared statement. command is used to execute either kind of prepared statement.
</para> </para>
</refsect1> </refsect1>
@ -7338,7 +7338,7 @@ EXEC SQL EXECUTE foo USING SQL DESCRIPTOR indesc INTO SQL DESCRIPTOR outdesc;
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="sql-execute"></member> <member><xref linkend="sql-execute"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>
@ -7445,8 +7445,8 @@ EXEC SQL SET CONNECTION = con1;
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="ecpg-sql-connect"></member> <member><xref linkend="ecpg-sql-connect"/></member>
<member><xref linkend="ecpg-sql-disconnect"></member> <member><xref linkend="ecpg-sql-disconnect"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>
@ -7520,7 +7520,7 @@ SET DESCRIPTOR <replaceable class="parameter">descriptor_name</replaceable> VALU
<listitem> <listitem>
<para> <para>
A token identifying which item of information to set in the A token identifying which item of information to set in the
descriptor. See <xref linkend="ecpg-named-descriptors"> for a descriptor. See <xref linkend="ecpg-named-descriptors"/> for a
list of supported items. list of supported items.
</para> </para>
</listitem> </listitem>
@ -7561,8 +7561,8 @@ EXEC SQL SET DESCRIPTOR indesc VALUE 2 INDICATOR = :val2null, DATA = :val2;
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="ecpg-sql-allocate-descriptor"></member> <member><xref linkend="ecpg-sql-allocate-descriptor"/></member>
<member><xref linkend="ecpg-sql-get-descriptor"></member> <member><xref linkend="ecpg-sql-get-descriptor"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>
@ -7796,7 +7796,7 @@ WHENEVER { NOT FOUND | SQLERROR | SQLWARNING } <replaceable class="parameter">ac
<title>Parameters</title> <title>Parameters</title>
<para> <para>
See <xref linkend="ecpg-whenever"> for a description of the See <xref linkend="ecpg-whenever"/> for a description of the
parameters. parameters.
</para> </para>
</refsect1> </refsect1>
@ -7979,7 +7979,7 @@ EXEC SQL CLOSE DATABASE;
<title>Informix-compatible SQLDA Descriptor Areas</title> <title>Informix-compatible SQLDA Descriptor Areas</title>
<para> <para>
Informix-compatible mode supports a different structure than the one described in Informix-compatible mode supports a different structure than the one described in
<xref linkend="ecpg-sqlda-descriptors">. See below: <xref linkend="ecpg-sqlda-descriptors"/>. See below:
<programlisting> <programlisting>
struct sqlvar_compat struct sqlvar_compat
{ {
@ -8653,7 +8653,7 @@ void rtoday(date *d);
that it sets to the current date. that it sets to the current date.
</para> </para>
<para> <para>
Internally this function uses the <xref linkend="pgtypesdatetoday"> Internally this function uses the <xref linkend="pgtypesdatetoday"/>
function. function.
</para> </para>
</listitem> </listitem>
@ -8678,7 +8678,7 @@ int rjulmdy(date d, short mdy[3]);
The function always returns 0 at the moment. The function always returns 0 at the moment.
</para> </para>
<para> <para>
Internally the function uses the <xref linkend="pgtypesdatejulmdy"> Internally the function uses the <xref linkend="pgtypesdatejulmdy"/>
function. function.
</para> </para>
</listitem> </listitem>
@ -8748,7 +8748,7 @@ int rdefmtdate(date *d, char *fmt, char *str);
</para> </para>
<para> <para>
Internally this function is implemented to use the <xref Internally this function is implemented to use the <xref
linkend="pgtypesdatedefmtasc"> function. See the reference there for a linkend="pgtypesdatedefmtasc"/> function. See the reference there for a
table of example input. table of example input.
</para> </para>
</listitem> </listitem>
@ -8771,7 +8771,7 @@ int rfmtdate(date d, char *fmt, char *str);
On success, 0 is returned and a negative value if an error occurred. On success, 0 is returned and a negative value if an error occurred.
</para> </para>
<para> <para>
Internally this function uses the <xref linkend="pgtypesdatefmtasc"> Internally this function uses the <xref linkend="pgtypesdatefmtasc"/>
function, see the reference there for examples. function, see the reference there for examples.
</para> </para>
</listitem> </listitem>
@ -8795,7 +8795,7 @@ int rmdyjul(short mdy[3], date *d);
</para> </para>
<para> <para>
Internally the function is implemented to use the function <xref Internally the function is implemented to use the function <xref
linkend="pgtypesdatemdyjul">. linkend="pgtypesdatemdyjul"/>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -8851,7 +8851,7 @@ int rdayofweek(date d);
</para> </para>
<para> <para>
Internally the function is implemented to use the function <xref Internally the function is implemented to use the function <xref
linkend="pgtypesdatedayofweek">. linkend="pgtypesdatedayofweek"/>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -8889,7 +8889,7 @@ int dtcvasc(char *str, timestamp *ts);
</para> </para>
<para> <para>
Internally this function uses the <xref Internally this function uses the <xref
linkend="pgtypestimestampfromasc"> function. See the reference there linkend="pgtypestimestampfromasc"/> function. See the reference there
for a table with example inputs. for a table with example inputs.
</para> </para>
</listitem> </listitem>
@ -8911,7 +8911,7 @@ dtcvfmtasc(char *inbuf, char *fmtstr, timestamp *dtvalue)
</para> </para>
<para> <para>
This function is implemented by means of the <xref This function is implemented by means of the <xref
linkend="pgtypestimestampdefmtasc"> function. See the documentation linkend="pgtypestimestampdefmtasc"/> function. See the documentation
there for a list of format specifiers that can be used. there for a list of format specifiers that can be used.
</para> </para>
<para> <para>
@ -8983,7 +8983,7 @@ int dttofmtasc(timestamp *ts, char *output, int str_len, char *fmtstr);
</para> </para>
<para> <para>
Internally, this function uses the <xref Internally, this function uses the <xref
linkend="pgtypestimestampfmtasc"> function. See the reference there for linkend="pgtypestimestampfmtasc"/> function. See the reference there for
information on what format mask specifiers can be used. information on what format mask specifiers can be used.
</para> </para>
</listitem> </listitem>
@ -9289,7 +9289,7 @@ int risnull(int t, char *ptr);
The function receives the type of the variable to test (<literal>t</literal>) The function receives the type of the variable to test (<literal>t</literal>)
as well a pointer to this variable (<literal>ptr</literal>). Note that the as well a pointer to this variable (<literal>ptr</literal>). Note that the
latter needs to be cast to a char*. See the function <xref latter needs to be cast to a char*. See the function <xref
linkend="rsetnull"> for a list of possible variable types. linkend="rsetnull"/> for a list of possible variable types.
</para> </para>
<para> <para>
Here is an example of how to use this function: Here is an example of how to use this function:

8
doc/src/sgml/errcodes.sgml
View File

@ -32,7 +32,7 @@
</para> </para>
<para> <para>
<xref linkend="errcodes-table"> lists all the error codes defined in <xref linkend="errcodes-table"/> lists all the error codes defined in
<productname>PostgreSQL</productname> &version;. (Some are not actually <productname>PostgreSQL</productname> &version;. (Some are not actually
used at present, but are defined by the SQL standard.) used at present, but are defined by the SQL standard.)
The error classes are also shown. For each error class there is a The error classes are also shown. For each error class there is a
@ -66,9 +66,9 @@
<title><productname>PostgreSQL</productname> Error Codes</title> <title><productname>PostgreSQL</productname> Error Codes</title>
<tgroup cols="2"> <tgroup cols="2">
<colspec colnum="1" colname="errorcode"> <colspec colnum="1" colname="errorcode"/>
<colspec colnum="2" colname="condname"> <colspec colnum="2" colname="condname"/>
<spanspec namest="errorcode" nameend="condname" spanname="span12"> <spanspec namest="errorcode" nameend="condname" spanname="span12"/>
<thead> <thead>
<row> <row>

18
doc/src/sgml/event-trigger.sgml
View File

@ -8,7 +8,7 @@
</indexterm> </indexterm>
<para> <para>
To supplement the trigger mechanism discussed in <xref linkend="triggers">, To supplement the trigger mechanism discussed in <xref linkend="triggers"/>,
<productname>PostgreSQL</productname> also provides event triggers. Unlike regular <productname>PostgreSQL</productname> also provides event triggers. Unlike regular
triggers, which are attached to a single table and capture only DML events, triggers, which are attached to a single table and capture only DML events,
event triggers are global to a particular database and are capable of event triggers are global to a particular database and are capable of
@ -57,7 +57,7 @@
operations that took place, use the set-returning function operations that took place, use the set-returning function
<literal>pg_event_trigger_ddl_commands()</literal> from the <literal>pg_event_trigger_ddl_commands()</literal> from the
<literal>ddl_command_end</literal> event trigger code (see <literal>ddl_command_end</literal> event trigger code (see
<xref linkend="functions-event-triggers">). Note that the trigger fires <xref linkend="functions-event-triggers"/>). Note that the trigger fires
after the actions have taken place (but before the transaction commits), after the actions have taken place (but before the transaction commits),
and thus the system catalogs can be read as already changed. and thus the system catalogs can be read as already changed.
</para> </para>
@ -68,7 +68,7 @@
database objects. To list the objects that have been dropped, use the database objects. To list the objects that have been dropped, use the
set-returning function <literal>pg_event_trigger_dropped_objects()</literal> from the set-returning function <literal>pg_event_trigger_dropped_objects()</literal> from the
<literal>sql_drop</literal> event trigger code (see <literal>sql_drop</literal> event trigger code (see
<xref linkend="functions-event-triggers">). Note that <xref linkend="functions-event-triggers"/>). Note that
the trigger is executed after the objects have been deleted from the the trigger is executed after the objects have been deleted from the
system catalogs, so it's not possible to look them up anymore. system catalogs, so it's not possible to look them up anymore.
</para> </para>
@ -96,11 +96,11 @@
<para> <para>
For a complete list of commands supported by the event trigger mechanism, For a complete list of commands supported by the event trigger mechanism,
see <xref linkend="event-trigger-matrix">. see <xref linkend="event-trigger-matrix"/>.
</para> </para>
<para> <para>
Event triggers are created using the command <xref linkend="sql-createeventtrigger">. Event triggers are created using the command <xref linkend="sql-createeventtrigger"/>.
In order to create an event trigger, you must first create a function with In order to create an event trigger, you must first create a function with
the special return type <literal>event_trigger</literal>. This function the special return type <literal>event_trigger</literal>. This function
need not (and may not) return a value; the return type serves merely as need not (and may not) return a value; the return type serves merely as
@ -125,7 +125,7 @@
<title>Event Trigger Firing Matrix</title> <title>Event Trigger Firing Matrix</title>
<para> <para>
<xref linkend="event-trigger-by-command-tag"> lists all commands <xref linkend="event-trigger-by-command-tag"/> lists all commands
for which event triggers are supported. for which event triggers are supported.
</para> </para>
@ -953,7 +953,7 @@ typedef struct EventTriggerData
Describes the event for which the function is called, one of Describes the event for which the function is called, one of
<literal>"ddl_command_start"</literal>, <literal>"ddl_command_end"</literal>, <literal>"ddl_command_start"</literal>, <literal>"ddl_command_end"</literal>,
<literal>"sql_drop"</literal>, <literal>"table_rewrite"</literal>. <literal>"sql_drop"</literal>, <literal>"table_rewrite"</literal>.
See <xref linkend="event-trigger-definition"> for the meaning of these See <xref linkend="event-trigger-definition"/> for the meaning of these
events. events.
</para> </para>
</listitem> </listitem>
@ -1003,7 +1003,7 @@ typedef struct EventTriggerData
The event trigger definition associated the function with The event trigger definition associated the function with
the <literal>ddl_command_start</literal> event. The effect is that all DDL the <literal>ddl_command_start</literal> event. The effect is that all DDL
commands (with the exceptions mentioned commands (with the exceptions mentioned
in <xref linkend="event-trigger-definition">) are prevented from running. in <xref linkend="event-trigger-definition"/>) are prevented from running.
</para> </para>
<para> <para>
@ -1037,7 +1037,7 @@ noddl(PG_FUNCTION_ARGS)
</para> </para>
<para> <para>
After you have compiled the source code (see <xref linkend="dfunc">), After you have compiled the source code (see <xref linkend="dfunc"/>),
declare the function and the triggers: declare the function and the triggers:
<programlisting> <programlisting>
CREATE FUNCTION noddl() RETURNS event_trigger CREATE FUNCTION noddl() RETURNS event_trigger

56
doc/src/sgml/extend.sgml
View File

@ -15,32 +15,32 @@
<itemizedlist spacing="compact" mark="bullet"> <itemizedlist spacing="compact" mark="bullet">
<listitem> <listitem>
<para> <para>
functions (starting in <xref linkend="xfunc">) functions (starting in <xref linkend="xfunc"/>)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
aggregates (starting in <xref linkend="xaggr">) aggregates (starting in <xref linkend="xaggr"/>)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
data types (starting in <xref linkend="xtypes">) data types (starting in <xref linkend="xtypes"/>)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
operators (starting in <xref linkend="xoper">) operators (starting in <xref linkend="xoper"/>)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
operator classes for indexes (starting in <xref linkend="xindex">) operator classes for indexes (starting in <xref linkend="xindex"/>)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
packages of related objects (starting in <xref linkend="extend-extensions">) packages of related objects (starting in <xref linkend="extend-extensions"/>)
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -132,14 +132,14 @@
types through functions provided by the user and only understands types through functions provided by the user and only understands
the behavior of such types to the extent that the user describes the behavior of such types to the extent that the user describes
them. them.
The built-in base types are described in <xref linkend="datatype">. The built-in base types are described in <xref linkend="datatype"/>.
</para> </para>
<para> <para>
Enumerated (enum) types can be considered as a subcategory of base Enumerated (enum) types can be considered as a subcategory of base
types. The main difference is that they can be created using types. The main difference is that they can be created using
just <acronym>SQL</acronym> commands, without any low-level programming. just <acronym>SQL</acronym> commands, without any low-level programming.
Refer to <xref linkend="datatype-enum"> for more information. Refer to <xref linkend="datatype-enum"/> for more information.
</para> </para>
</sect2> </sect2>
@ -157,25 +157,25 @@
type is automatically created for each base type, composite type, range type is automatically created for each base type, composite type, range
type, and domain type. But there are no arrays of arrays. So far as type, and domain type. But there are no arrays of arrays. So far as
the type system is concerned, multi-dimensional arrays are the same as the type system is concerned, multi-dimensional arrays are the same as
one-dimensional arrays. Refer to <xref linkend="arrays"> for more one-dimensional arrays. Refer to <xref linkend="arrays"/> for more
information. information.
</para> </para>
<para> <para>
Composite types, or row types, are created whenever the user Composite types, or row types, are created whenever the user
creates a table. It is also possible to use <xref creates a table. It is also possible to use <xref
linkend="sql-createtype"> to linkend="sql-createtype"/> to
define a <quote>stand-alone</quote> composite type with no associated define a <quote>stand-alone</quote> composite type with no associated
table. A composite type is simply a list of types with table. A composite type is simply a list of types with
associated field names. A value of a composite type is a row or associated field names. A value of a composite type is a row or
record of field values. Refer to <xref linkend="rowtypes"> record of field values. Refer to <xref linkend="rowtypes"/>
for more information. for more information.
</para> </para>
<para> <para>
A range type can hold two values of the same type, which are the lower A range type can hold two values of the same type, which are the lower
and upper bounds of the range. Range types are user-created, although and upper bounds of the range. Range types are user-created, although
a few built-in ones exist. Refer to <xref linkend="rangetypes"> a few built-in ones exist. Refer to <xref linkend="rangetypes"/>
for more information. for more information.
</para> </para>
</sect2> </sect2>
@ -188,8 +188,8 @@
is interchangeable with its underlying type. However, a domain can have is interchangeable with its underlying type. However, a domain can have
constraints that restrict its valid values to a subset of what the constraints that restrict its valid values to a subset of what the
underlying type would allow. Domains are created using underlying type would allow. Domains are created using
the <acronym>SQL</acronym> command <xref linkend="sql-createdomain">. the <acronym>SQL</acronym> command <xref linkend="sql-createdomain"/>.
Refer to <xref linkend="domains"> for more information. Refer to <xref linkend="domains"/> for more information.
</para> </para>
</sect2> </sect2>
@ -202,7 +202,7 @@
container types, but they can be used to declare the argument and container types, but they can be used to declare the argument and
result types of functions. This provides a mechanism within the result types of functions. This provides a mechanism within the
type system to identify special classes of functions. <xref type system to identify special classes of functions. <xref
linkend="datatype-pseudotypes-table"> lists the existing linkend="datatype-pseudotypes-table"/> lists the existing
pseudo-types. pseudo-types.
</para> </para>
</sect2> </sect2>
@ -300,7 +300,7 @@
<para> <para>
A variadic function (one taking a variable number of arguments, as in A variadic function (one taking a variable number of arguments, as in
<xref linkend="xfunc-sql-variadic-functions">) can be <xref linkend="xfunc-sql-variadic-functions"/>) can be
polymorphic: this is accomplished by declaring its last parameter as polymorphic: this is accomplished by declaring its last parameter as
<literal>VARIADIC</literal> <type>anyarray</type>. For purposes of argument <literal>VARIADIC</literal> <type>anyarray</type>. For purposes of argument
matching and determining the actual result type, such a function behaves matching and determining the actual result type, such a function behaves
@ -337,7 +337,7 @@
of the extension itself. If the extension includes C code, there of the extension itself. If the extension includes C code, there
will typically also be a shared library file into which the C code will typically also be a shared library file into which the C code
has been built. Once you have these files, a simple has been built. Once you have these files, a simple
<xref linkend="sql-createextension"> command loads the objects into <xref linkend="sql-createextension"/> command loads the objects into
your database. your database.
</para> </para>
@ -346,7 +346,7 @@
<acronym>SQL</acronym> script to load a bunch of <quote>loose</quote> objects <acronym>SQL</acronym> script to load a bunch of <quote>loose</quote> objects
into your database, is that <productname>PostgreSQL</productname> will then into your database, is that <productname>PostgreSQL</productname> will then
understand that the objects of the extension go together. You can understand that the objects of the extension go together. You can
drop all the objects with a single <xref linkend="sql-dropextension"> drop all the objects with a single <xref linkend="sql-dropextension"/>
command (no need to maintain a separate <quote>uninstall</quote> script). command (no need to maintain a separate <quote>uninstall</quote> script).
Even more useful, <application>pg_dump</application> knows that it should not Even more useful, <application>pg_dump</application> knows that it should not
dump the individual member objects of the extension &mdash; it will dump the individual member objects of the extension &mdash; it will
@ -366,7 +366,7 @@
by <application>pg_dump</application>. Such a change is usually only sensible if by <application>pg_dump</application>. Such a change is usually only sensible if
you concurrently make the same change in the extension's script file. you concurrently make the same change in the extension's script file.
(But there are special provisions for tables containing configuration (But there are special provisions for tables containing configuration
data; see <xref linkend="extend-extensions-config-tables">.) data; see <xref linkend="extend-extensions-config-tables"/>.)
In production situations, it's generally better to create an extension In production situations, it's generally better to create an extension
update script to perform changes to extension member objects. update script to perform changes to extension member objects.
</para> </para>
@ -405,7 +405,7 @@
<para> <para>
The kinds of SQL objects that can be members of an extension are shown in The kinds of SQL objects that can be members of an extension are shown in
the description of <xref linkend="sql-alterextension">. Notably, objects the description of <xref linkend="sql-alterextension"/>. Notably, objects
that are database-cluster-wide, such as databases, roles, and tablespaces, that are database-cluster-wide, such as databases, roles, and tablespaces,
cannot be extension members since an extension is only known within one cannot be extension members since an extension is only known within one
database. (Although an extension script is not prohibited from creating database. (Although an extension script is not prohibited from creating
@ -438,7 +438,7 @@
</indexterm> </indexterm>
<para> <para>
The <xref linkend="sql-createextension"> command relies on a control The <xref linkend="sql-createextension"/> command relies on a control
file for each extension, which must be named the same as the extension file for each extension, which must be named the same as the extension
with a suffix of <literal>.control</literal>, and must be placed in the with a suffix of <literal>.control</literal>, and must be placed in the
installation's <literal>SHAREDIR/extension</literal> directory. There installation's <literal>SHAREDIR/extension</literal> directory. There
@ -499,7 +499,7 @@
when initially creating an extension, but not during extension updates when initially creating an extension, but not during extension updates
(since that might override user-added comments). Alternatively, (since that might override user-added comments). Alternatively,
the extension's comment can be set by writing the extension's comment can be set by writing
a <xref linkend="sql-comment"> command in the script file. a <xref linkend="sql-comment"/> command in the script file.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -562,7 +562,7 @@
its contained objects into a different schema after initial creation its contained objects into a different schema after initial creation
of the extension. The default is <literal>false</literal>, i.e. the of the extension. The default is <literal>false</literal>, i.e. the
extension is not relocatable. extension is not relocatable.
See <xref linkend="extend-extensions-relocation"> for more information. See <xref linkend="extend-extensions-relocation"/> for more information.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -576,7 +576,7 @@
and not any other. and not any other.
The <varname>schema</varname> parameter is consulted only when The <varname>schema</varname> parameter is consulted only when
initially creating an extension, not during extension updates. initially creating an extension, not during extension updates.
See <xref linkend="extend-extensions-relocation"> for more information. See <xref linkend="extend-extensions-relocation"/> for more information.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -609,7 +609,7 @@
comments) by the extension mechanism. This provision is commonly used comments) by the extension mechanism. This provision is commonly used
to throw an error if the script file is fed to <application>psql</application> to throw an error if the script file is fed to <application>psql</application>
rather than being loaded via <command>CREATE EXTENSION</command> (see example rather than being loaded via <command>CREATE EXTENSION</command> (see example
script in <xref linkend="extend-extensions-example">). script in <xref linkend="extend-extensions-example"/>).
Without that, users might accidentally load the Without that, users might accidentally load the
extension's contents as <quote>loose</quote> objects rather than as an extension's contents as <quote>loose</quote> objects rather than as an
extension, a state of affairs that's a bit tedious to recover from. extension, a state of affairs that's a bit tedious to recover from.
@ -687,7 +687,7 @@
<para> <para>
In all cases, the script file will be executed with In all cases, the script file will be executed with
<xref linkend="guc-search-path"> initially set to point to the target <xref linkend="guc-search-path"/> initially set to point to the target
schema; that is, <command>CREATE EXTENSION</command> does the equivalent of schema; that is, <command>CREATE EXTENSION</command> does the equivalent of
this: this:
<programlisting> <programlisting>
@ -1031,14 +1031,14 @@ include $(PGXS)
</programlisting> </programlisting>
This makefile relies on <acronym>PGXS</acronym>, which is described This makefile relies on <acronym>PGXS</acronym>, which is described
in <xref linkend="extend-pgxs">. The command <literal>make install</literal> in <xref linkend="extend-pgxs"/>. The command <literal>make install</literal>
will install the control and script files into the correct will install the control and script files into the correct
directory as reported by <application>pg_config</application>. directory as reported by <application>pg_config</application>.
</para> </para>
<para> <para>
Once the files are installed, use the Once the files are installed, use the
<xref linkend="sql-createextension"> command to load the objects into <xref linkend="sql-createextension"/> command to load the objects into
any particular database. any particular database.
</para> </para>
</sect2> </sect2>

6
doc/src/sgml/external-projects.sgml
View File

@ -40,7 +40,7 @@
</itemizedlist> </itemizedlist>
All other language interfaces are external projects and are distributed All other language interfaces are external projects and are distributed
separately. <xref linkend="language-interface-table"> includes a list of separately. <xref linkend="language-interface-table"/> includes a list of
some of these projects. Note that some of these packages might not be some of these projects. Note that some of these packages might not be
released under the same license as <productname>PostgreSQL</productname>. For more released under the same license as <productname>PostgreSQL</productname>. For more
information on each language interface, including licensing terms, refer to information on each language interface, including licensing terms, refer to
@ -170,7 +170,7 @@
<para> <para>
In addition, there are a number of procedural languages that are developed In addition, there are a number of procedural languages that are developed
and maintained outside the core <productname>PostgreSQL</productname> and maintained outside the core <productname>PostgreSQL</productname>
distribution. <xref linkend="pl-language-table"> lists some of these distribution. <xref linkend="pl-language-table"/> lists some of these
packages. Note that some of these projects might not be released under the same packages. Note that some of these projects might not be released under the same
license as <productname>PostgreSQL</productname>. For more information on each license as <productname>PostgreSQL</productname>. For more information on each
procedural language, including licensing information, refer to its website procedural language, including licensing information, refer to its website
@ -238,7 +238,7 @@
just like features that are built in. The just like features that are built in. The
<filename>contrib/</filename> directory shipped with the source code <filename>contrib/</filename> directory shipped with the source code
contains several extensions, which are described in contains several extensions, which are described in
<xref linkend="contrib">. Other extensions are developed <xref linkend="contrib"/>. Other extensions are developed
independently, like <application><ulink independently, like <application><ulink
url="http://postgis.net/">PostGIS</ulink></application>. Even url="http://postgis.net/">PostGIS</ulink></application>. Even
<productname>PostgreSQL</productname> replication solutions can be developed <productname>PostgreSQL</productname> replication solutions can be developed

40
doc/src/sgml/fdwhandler.sgml
View File

@ -22,7 +22,7 @@
The foreign data wrappers included in the standard distribution are good The foreign data wrappers included in the standard distribution are good
references when trying to write your own. Look into the references when trying to write your own. Look into the
<filename>contrib</filename> subdirectory of the source tree. <filename>contrib</filename> subdirectory of the source tree.
The <xref linkend="sql-createforeigndatawrapper"> reference page also has The <xref linkend="sql-createforeigndatawrapper"/> reference page also has
some useful details. some useful details.
</para> </para>
@ -43,7 +43,7 @@
a validator function. Both functions must be written in a compiled a validator function. Both functions must be written in a compiled
language such as C, using the version-1 interface. language such as C, using the version-1 interface.
For details on C language calling conventions and dynamic loading, For details on C language calling conventions and dynamic loading,
see <xref linkend="xfunc-c">. see <xref linkend="xfunc-c"/>.
</para> </para>
<para> <para>
@ -57,7 +57,7 @@
returning the special pseudo-type <type>fdw_handler</type>. The returning the special pseudo-type <type>fdw_handler</type>. The
callback functions are plain C functions and are not visible or callback functions are plain C functions and are not visible or
callable at the SQL level. The callback functions are described in callable at the SQL level. The callback functions are described in
<xref linkend="fdw-callbacks">. <xref linkend="fdw-callbacks"/>.
</para> </para>
<para> <para>
@ -126,7 +126,7 @@ GetForeignRelSize(PlannerInfo *root,
</para> </para>
<para> <para>
See <xref linkend="fdw-planning"> for additional information. See <xref linkend="fdw-planning"/> for additional information.
</para> </para>
<para> <para>
@ -157,7 +157,7 @@ GetForeignPaths(PlannerInfo *root,
</para> </para>
<para> <para>
See <xref linkend="fdw-planning"> for additional information. See <xref linkend="fdw-planning"/> for additional information.
</para> </para>
<para> <para>
@ -193,7 +193,7 @@ GetForeignPlan(PlannerInfo *root,
</para> </para>
<para> <para>
See <xref linkend="fdw-planning"> for additional information. See <xref linkend="fdw-planning"/> for additional information.
</para> </para>
<para> <para>
@ -341,7 +341,7 @@ GetForeignJoinPaths(PlannerInfo *root,
</para> </para>
<para> <para>
See <xref linkend="fdw-planning"> for additional information. See <xref linkend="fdw-planning"/> for additional information.
</para> </para>
</sect2> </sect2>
@ -388,7 +388,7 @@ GetForeignUpperPaths(PlannerInfo *root,
</para> </para>
<para> <para>
See <xref linkend="fdw-planning"> for additional information. See <xref linkend="fdw-planning"/> for additional information.
</para> </para>
</sect2> </sect2>
@ -477,7 +477,7 @@ PlanForeignModify(PlannerInfo *root,
</para> </para>
<para> <para>
See <xref linkend="fdw-planning"> for additional information. See <xref linkend="fdw-planning"/> for additional information.
</para> </para>
<para> <para>
@ -759,7 +759,7 @@ PlanDirectModify(PlannerInfo *root,
</para> </para>
<para> <para>
See <xref linkend="fdw-planning"> for additional information. See <xref linkend="fdw-planning"/> for additional information.
</para> </para>
<para> <para>
@ -872,7 +872,7 @@ EndDirectModify(ForeignScanState *node);
<para> <para>
If an FDW wishes to support <firstterm>late row locking</firstterm> (as described If an FDW wishes to support <firstterm>late row locking</firstterm> (as described
in <xref linkend="fdw-row-locking">), it must provide the following in <xref linkend="fdw-row-locking"/>), it must provide the following
callback functions: callback functions:
</para> </para>
@ -905,7 +905,7 @@ GetForeignRowMarkType(RangeTblEntry *rte,
</para> </para>
<para> <para>
See <xref linkend="fdw-row-locking"> for more information. See <xref linkend="fdw-row-locking"/> for more information.
</para> </para>
<para> <para>
@ -964,7 +964,7 @@ RefetchForeignRow(EState *estate,
</para> </para>
<para> <para>
See <xref linkend="fdw-row-locking"> for more information. See <xref linkend="fdw-row-locking"/> for more information.
</para> </para>
<para> <para>
@ -1093,7 +1093,7 @@ AnalyzeForeignTable(Relation relation,
BlockNumber *totalpages); BlockNumber *totalpages);
</programlisting> </programlisting>
This function is called when <xref linkend="sql-analyze"> is executed on This function is called when <xref linkend="sql-analyze"/> is executed on
a foreign table. If the FDW can collect statistics for this a foreign table. If the FDW can collect statistics for this
foreign table, it should return <literal>true</literal>, and provide a pointer foreign table, it should return <literal>true</literal>, and provide a pointer
to a function that will collect sample rows from the table in to a function that will collect sample rows from the table in
@ -1139,10 +1139,10 @@ ImportForeignSchema(ImportForeignSchemaStmt *stmt, Oid serverOid);
</programlisting> </programlisting>
Obtain a list of foreign table creation commands. This function is Obtain a list of foreign table creation commands. This function is
called when executing <xref linkend="sql-importforeignschema">, and is called when executing <xref linkend="sql-importforeignschema"/>, and is
passed the parse tree for that statement, as well as the OID of the passed the parse tree for that statement, as well as the OID of the
foreign server to use. It should return a list of C strings, each of foreign server to use. It should return a list of C strings, each of
which must contain a <xref linkend="sql-createforeigntable"> command. which must contain a <xref linkend="sql-createforeigntable"/> command.
These strings will be parsed and executed by the core server. These strings will be parsed and executed by the core server.
</para> </para>
@ -1605,7 +1605,7 @@ GetForeignServerByName(const char *name, bool missing_ok);
<para> <para>
<function>PlanForeignModify</function> and the other callbacks described in <function>PlanForeignModify</function> and the other callbacks described in
<xref linkend="fdw-callbacks-update"> are designed around the assumption <xref linkend="fdw-callbacks-update"/> are designed around the assumption
that the foreign relation will be scanned in the usual way and then that the foreign relation will be scanned in the usual way and then
individual row updates will be driven by a local <literal>ModifyTable</literal> individual row updates will be driven by a local <literal>ModifyTable</literal>
plan node. This approach is necessary for the general case where an plan node. This approach is necessary for the general case where an
@ -1616,7 +1616,7 @@ GetForeignServerByName(const char *name, bool missing_ok);
compete against the <literal>ModifyTable</literal> approach. This approach compete against the <literal>ModifyTable</literal> approach. This approach
could also be used to implement remote <literal>SELECT FOR UPDATE</literal>, could also be used to implement remote <literal>SELECT FOR UPDATE</literal>,
rather than using the row locking callbacks described in rather than using the row locking callbacks described in
<xref linkend="fdw-callbacks-row-locking">. Keep in mind that a path <xref linkend="fdw-callbacks-row-locking"/>. Keep in mind that a path
inserted into <literal>UPPERREL_FINAL</literal> is responsible for inserted into <literal>UPPERREL_FINAL</literal> is responsible for
implementing <emphasis>all</emphasis> behavior of the query. implementing <emphasis>all</emphasis> behavior of the query.
</para> </para>
@ -1676,7 +1676,7 @@ GetForeignServerByName(const char *name, bool missing_ok);
By default, <productname>PostgreSQL</productname> ignores locking considerations By default, <productname>PostgreSQL</productname> ignores locking considerations
when interfacing to FDWs, but an FDW can perform early locking without when interfacing to FDWs, but an FDW can perform early locking without
any explicit support from the core code. The API functions described any explicit support from the core code. The API functions described
in <xref linkend="fdw-callbacks-row-locking">, which were added in <xref linkend="fdw-callbacks-row-locking"/>, which were added
in <productname>PostgreSQL</productname> 9.5, allow an FDW to use late locking if in <productname>PostgreSQL</productname> 9.5, allow an FDW to use late locking if
it wishes. it wishes.
</para> </para>
@ -1720,7 +1720,7 @@ GetForeignServerByName(const char *name, bool missing_ok);
again perform early locking by fetching tuples with the equivalent again perform early locking by fetching tuples with the equivalent
of <command>SELECT FOR UPDATE/SHARE</command>. To perform late locking of <command>SELECT FOR UPDATE/SHARE</command>. To perform late locking
instead, provide the callback functions defined instead, provide the callback functions defined
in <xref linkend="fdw-callbacks-row-locking">. in <xref linkend="fdw-callbacks-row-locking"/>.
In <function>GetForeignRowMarkType</function>, select rowmark option In <function>GetForeignRowMarkType</function>, select rowmark option
<literal>ROW_MARK_EXCLUSIVE</literal>, <literal>ROW_MARK_NOKEYEXCLUSIVE</literal>, <literal>ROW_MARK_EXCLUSIVE</literal>, <literal>ROW_MARK_NOKEYEXCLUSIVE</literal>,
<literal>ROW_MARK_SHARE</literal>, or <literal>ROW_MARK_KEYSHARE</literal> depending <literal>ROW_MARK_SHARE</literal>, or <literal>ROW_MARK_KEYSHARE</literal> depending

2
doc/src/sgml/file-fdw.sgml
View File

@ -13,7 +13,7 @@
files in the server's file system, or to execute programs on the server 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 and read their output. The data file or program output must be in a format
that can be read by <command>COPY FROM</command>; that can be read by <command>COPY FROM</command>;
see <xref linkend="sql-copy"> for details. see <xref linkend="sql-copy"/> for details.
Access to data files is currently read-only. Access to data files is currently read-only.
</para> </para>

520
doc/src/sgml/func.sgml
View File

File diff suppressed because it is too large Load Diff

6
doc/src/sgml/geqo.sgml
View File

@ -237,7 +237,7 @@
choices made during both the initial population selection and subsequent choices made during both the initial population selection and subsequent
<quote>mutation</quote> of the best candidates. To avoid surprising changes <quote>mutation</quote> of the best candidates. To avoid surprising changes
of the selected plan, each run of the GEQO algorithm restarts its of the selected plan, each run of the GEQO algorithm restarts its
random number generator with the current <xref linkend="guc-geqo-seed"> random number generator with the current <xref linkend="guc-geqo-seed"/>
parameter setting. As long as <varname>geqo_seed</varname> and the other parameter setting. As long as <varname>geqo_seed</varname> and the other
GEQO parameters are kept fixed, the same plan will be generated for a GEQO parameters are kept fixed, the same plan will be generated for a
given query (and other planner inputs such as statistics). To experiment given query (and other planner inputs such as statistics). To experiment
@ -320,13 +320,13 @@
<listitem> <listitem>
<para> <para>
<xref linkend="elma04"> <xref linkend="elma04"/>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<xref linkend="fong"> <xref linkend="fong"/>
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>

24
doc/src/sgml/gin.sgml
View File

@ -68,8 +68,8 @@
<para> <para>
The core <productname>PostgreSQL</productname> distribution The core <productname>PostgreSQL</productname> distribution
includes the <acronym>GIN</acronym> operator classes shown in includes the <acronym>GIN</acronym> operator classes shown in
<xref linkend="gin-builtin-opclasses-table">. <xref linkend="gin-builtin-opclasses-table"/>.
(Some of the optional modules described in <xref linkend="contrib"> (Some of the optional modules described in <xref linkend="contrib"/>
provide additional <acronym>GIN</acronym> operator classes.) provide additional <acronym>GIN</acronym> operator classes.)
</para> </para>
@ -127,7 +127,7 @@
Of the two operator classes for type <type>jsonb</type>, <literal>jsonb_ops</literal> Of the two operator classes for type <type>jsonb</type>, <literal>jsonb_ops</literal>
is the default. <literal>jsonb_path_ops</literal> supports fewer operators but is the default. <literal>jsonb_path_ops</literal> supports fewer operators but
offers better performance for those operators. offers better performance for those operators.
See <xref linkend="json-indexing"> for details. See <xref linkend="json-indexing"/> for details.
</para> </para>
</sect1> </sect1>
@ -182,7 +182,7 @@
<literal>query</literal> is the value on the right-hand side of an <literal>query</literal> is the value on the right-hand side of an
indexable operator whose left-hand side is the indexed column. indexable operator whose left-hand side is the indexed column.
<literal>n</literal> is the strategy number of the operator within the <literal>n</literal> is the strategy number of the operator within the
operator class (see <xref linkend="xindex-strategies">). operator class (see <xref linkend="xindex-strategies"/>).
Often, <function>extractQuery</function> will need Often, <function>extractQuery</function> will need
to consult <literal>n</literal> to determine the data type of to consult <literal>n</literal> to determine the data type of
<literal>query</literal> and the method it should use to extract key values. <literal>query</literal> and the method it should use to extract key values.
@ -406,7 +406,7 @@
provide the <function>comparePartial</function> method, and its provide the <function>comparePartial</function> method, and its
<function>extractQuery</function> method must set the <literal>pmatch</literal> <function>extractQuery</function> method must set the <literal>pmatch</literal>
parameter when a partial-match query is encountered. See parameter when a partial-match query is encountered. See
<xref linkend="gin-partial-match"> for details. <xref linkend="gin-partial-match"/> for details.
</para> </para>
<para> <para>
@ -466,7 +466,7 @@
When the table is vacuumed or autoanalyzed, or when When the table is vacuumed or autoanalyzed, or when
<function>gin_clean_pending_list</function> function is called, or if the <function>gin_clean_pending_list</function> function is called, or if the
pending list becomes larger than pending list becomes larger than
<xref linkend="guc-gin-pending-list-limit">, the entries are moved to the <xref linkend="guc-gin-pending-list-limit"/>, the entries are moved to the
main <acronym>GIN</acronym> data structure using the same bulk insert main <acronym>GIN</acronym> data structure using the same bulk insert
techniques used during initial index creation. This greatly improves techniques used during initial index creation. This greatly improves
<acronym>GIN</acronym> index update speed, even counting the additional <acronym>GIN</acronym> index update speed, even counting the additional
@ -488,7 +488,7 @@
If consistent response time is more important than update speed, If consistent response time is more important than update speed,
use of pending entries can be disabled by turning off the use of pending entries can be disabled by turning off the
<literal>fastupdate</literal> storage parameter for a <literal>fastupdate</literal> storage parameter for a
<acronym>GIN</acronym> index. See <xref linkend="sql-createindex"> <acronym>GIN</acronym> index. See <xref linkend="sql-createindex"/>
for details. for details.
</para> </para>
</sect2> </sect2>
@ -531,14 +531,14 @@
<para> <para>
As of <productname>PostgreSQL</productname> 8.4, this advice is less As of <productname>PostgreSQL</productname> 8.4, this advice is less
necessary since delayed indexing is used (see <xref necessary since delayed indexing is used (see <xref
linkend="gin-fast-update"> for details). But for very large updates linkend="gin-fast-update"/> for details). But for very large updates
it may still be best to drop and recreate the index. it may still be best to drop and recreate the index.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><xref linkend="guc-maintenance-work-mem"></term> <term><xref linkend="guc-maintenance-work-mem"/></term>
<listitem> <listitem>
<para> <para>
Build time for a <acronym>GIN</acronym> index is very sensitive to Build time for a <acronym>GIN</acronym> index is very sensitive to
@ -549,7 +549,7 @@
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><xref linkend="guc-gin-pending-list-limit"></term> <term><xref linkend="guc-gin-pending-list-limit"/></term>
<listitem> <listitem>
<para> <para>
During a series of insertions into an existing <acronym>GIN</acronym> During a series of insertions into an existing <acronym>GIN</acronym>
@ -574,7 +574,7 @@
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><xref linkend="guc-gin-fuzzy-search-limit"></term> <term><xref linkend="guc-gin-fuzzy-search-limit"/></term>
<listitem> <listitem>
<para> <para>
The primary goal of developing <acronym>GIN</acronym> indexes was The primary goal of developing <acronym>GIN</acronym> indexes was
@ -631,7 +631,7 @@
<para> <para>
The core <productname>PostgreSQL</productname> distribution The core <productname>PostgreSQL</productname> distribution
includes the <acronym>GIN</acronym> operator classes previously shown in includes the <acronym>GIN</acronym> operator classes previously shown in
<xref linkend="gin-builtin-opclasses-table">. <xref linkend="gin-builtin-opclasses-table"/>.
The following <filename>contrib</filename> modules also contain The following <filename>contrib</filename> modules also contain
<acronym>GIN</acronym> operator classes: <acronym>GIN</acronym> operator classes:

6
doc/src/sgml/gist.sgml
View File

@ -46,8 +46,8 @@
<para> <para>
The core <productname>PostgreSQL</productname> distribution The core <productname>PostgreSQL</productname> distribution
includes the <acronym>GiST</acronym> operator classes shown in includes the <acronym>GiST</acronym> operator classes shown in
<xref linkend="gist-builtin-opclasses-table">. <xref linkend="gist-builtin-opclasses-table"/>.
(Some of the optional modules described in <xref linkend="contrib"> (Some of the optional modules described in <xref linkend="contrib"/>
provide additional <acronym>GiST</acronym> operator classes.) provide additional <acronym>GiST</acronym> operator classes.)
</para> </para>
@ -985,7 +985,7 @@ my_fetch(PG_FUNCTION_ARGS)
<para> <para>
By default, a GiST index build switches to the buffering method when the By default, a GiST index build switches to the buffering method when the
index size reaches <xref linkend="guc-effective-cache-size">. It can index size reaches <xref linkend="guc-effective-cache-size"/>. It can
be manually turned on or off by the <literal>buffering</literal> parameter be manually turned on or off by the <literal>buffering</literal> parameter
to the CREATE INDEX command. The default behavior is good for most cases, to the CREATE INDEX command. The default behavior is good for most cases,
but turning buffering off might speed up the build somewhat if the input but turning buffering off might speed up the build somewhat if the input

154
doc/src/sgml/high-availability.sgml
View File

@ -100,7 +100,7 @@
Shared hardware functionality is common in network storage devices. Shared hardware functionality is common in network storage devices.
Using a network file system is also possible, though care must be Using a network file system is also possible, though care must be
taken that the file system has full <acronym>POSIX</acronym> behavior (see <xref taken that the file system has full <acronym>POSIX</acronym> behavior (see <xref
linkend="creating-cluster-nfs">). One significant limitation of this linkend="creating-cluster-nfs"/>). One significant limitation of this
method is that if the shared disk array fails or becomes corrupt, the method is that if the shared disk array fails or becomes corrupt, the
primary and standby servers are both nonfunctional. Another issue is primary and standby servers are both nonfunctional. Another issue is
that the standby server should never access the shared storage while that the standby server should never access the shared storage while
@ -151,9 +151,9 @@ protocol to make nodes agree on a serializable transactional order.
</para> </para>
<para> <para>
A standby server can be implemented using file-based log shipping A standby server can be implemented using file-based log shipping
(<xref linkend="warm-standby">) or streaming replication (see (<xref linkend="warm-standby"/>) or streaming replication (see
<xref linkend="streaming-replication">), or a combination of both. For <xref linkend="streaming-replication"/>), or a combination of both. For
information on hot standby, see <xref linkend="hot-standby">. information on hot standby, see <xref linkend="hot-standby"/>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -169,8 +169,8 @@ protocol to make nodes agree on a serializable transactional order.
individual tables to be replicated. Logical replication doesn't require individual tables to be replicated. Logical replication doesn't require
a particular server to be designated as a master or a replica but allows a particular server to be designated as a master or a replica but allows
data to flow in multiple directions. For more information on logical data to flow in multiple directions. For more information on logical
replication, see <xref linkend="logical-replication">. Through the replication, see <xref linkend="logical-replication"/>. Through the
logical decoding interface (<xref linkend="logicaldecoding">), logical decoding interface (<xref linkend="logicaldecoding"/>),
third-party extensions can also provide similar functionality. third-party extensions can also provide similar functionality.
</para> </para>
</listitem> </listitem>
@ -224,8 +224,8 @@ protocol to make nodes agree on a serializable transactional order.
standby servers via master-standby replication, not by the replication standby servers via master-standby replication, not by the replication
middleware. Care must also be taken that all middleware. Care must also be taken that all
transactions either commit or abort on all servers, perhaps transactions either commit or abort on all servers, perhaps
using two-phase commit (<xref linkend="sql-prepare-transaction"> using two-phase commit (<xref linkend="sql-prepare-transaction"/>
and <xref linkend="sql-commit-prepared">). and <xref linkend="sql-commit-prepared"/>).
<productname>Pgpool-II</productname> and <productname>Continuent Tungsten</productname> <productname>Pgpool-II</productname> and <productname>Continuent Tungsten</productname>
are examples of this type of replication. are examples of this type of replication.
</para> </para>
@ -272,8 +272,8 @@ protocol to make nodes agree on a serializable transactional order.
<para> <para>
<productname>PostgreSQL</productname> does not offer this type of replication, <productname>PostgreSQL</productname> does not offer this type of replication,
though <productname>PostgreSQL</productname> two-phase commit (<xref though <productname>PostgreSQL</productname> two-phase commit (<xref
linkend="sql-prepare-transaction"> and <xref linkend="sql-prepare-transaction"/> and <xref
linkend="sql-commit-prepared">) linkend="sql-commit-prepared"/>)
can be used to implement this in application code or middleware. can be used to implement this in application code or middleware.
</para> </para>
</listitem> </listitem>
@ -295,7 +295,7 @@ protocol to make nodes agree on a serializable transactional order.
</variablelist> </variablelist>
<para> <para>
<xref linkend="high-availability-matrix"> summarizes <xref linkend="high-availability-matrix"/> summarizes
the capabilities of the various solutions listed above. the capabilities of the various solutions listed above.
</para> </para>
@ -522,7 +522,7 @@ protocol to make nodes agree on a serializable transactional order.
varies according to the transaction rate of the primary server. varies according to the transaction rate of the primary server.
Record-based log shipping is more granular and streams WAL changes Record-based log shipping is more granular and streams WAL changes
incrementally over a network connection (see <xref incrementally over a network connection (see <xref
linkend="streaming-replication">). linkend="streaming-replication"/>).
</para> </para>
<para> <para>
@ -534,7 +534,7 @@ protocol to make nodes agree on a serializable transactional order.
<varname>archive_timeout</varname> parameter, which can be set as low <varname>archive_timeout</varname> parameter, which can be set as low
as a few seconds. However such a low setting will as a few seconds. However such a low setting will
substantially increase the bandwidth required for file shipping. substantially increase the bandwidth required for file shipping.
Streaming replication (see <xref linkend="streaming-replication">) Streaming replication (see <xref linkend="streaming-replication"/>)
allows a much smaller window of data loss. allows a much smaller window of data loss.
</para> </para>
@ -547,7 +547,7 @@ protocol to make nodes agree on a serializable transactional order.
rollforward will take considerably longer, so that technique only rollforward will take considerably longer, so that technique only
offers a solution for disaster recovery, not high availability. offers a solution for disaster recovery, not high availability.
A standby server can also be used for read-only queries, in which case A standby server can also be used for read-only queries, in which case
it is called a Hot Standby server. See <xref linkend="hot-standby"> for it is called a Hot Standby server. See <xref linkend="hot-standby"/> for
more information. more information.
</para> </para>
@ -585,7 +585,7 @@ protocol to make nodes agree on a serializable transactional order.
associated with tablespaces will be passed across unmodified, so both associated with tablespaces will be passed across unmodified, so both
primary and standby servers must have the same mount paths for primary and standby servers must have the same mount paths for
tablespaces if that feature is used. Keep in mind that if tablespaces if that feature is used. Keep in mind that if
<xref linkend="sql-createtablespace"> <xref linkend="sql-createtablespace"/>
is executed on the primary, any new mount point needed for it must is executed on the primary, any new mount point needed for it must
be created on the primary and all standby servers before the command be created on the primary and all standby servers before the command
is executed. Hardware need not be exactly the same, but experience shows is executed. Hardware need not be exactly the same, but experience shows
@ -618,7 +618,7 @@ protocol to make nodes agree on a serializable transactional order.
<para> <para>
In standby mode, the server continuously applies WAL received from the In standby mode, the server continuously applies WAL received from the
master server. The standby server can read WAL from a WAL archive master server. The standby server can read WAL from a WAL archive
(see <xref linkend="restore-command">) or directly from the master (see <xref linkend="restore-command"/>) or directly from the master
over a TCP connection (streaming replication). The standby server will over a TCP connection (streaming replication). The standby server will
also attempt to restore any WAL found in the standby cluster's also attempt to restore any WAL found in the standby cluster's
<filename>pg_wal</filename> directory. That typically happens after a server <filename>pg_wal</filename> directory. That typically happens after a server
@ -657,7 +657,7 @@ protocol to make nodes agree on a serializable transactional order.
<para> <para>
Set up continuous archiving on the primary to an archive directory Set up continuous archiving on the primary to an archive directory
accessible from the standby, as described accessible from the standby, as described
in <xref linkend="continuous-archiving">. The archive location should be in <xref linkend="continuous-archiving"/>. The archive location should be
accessible from the standby even when the master is down, i.e. it should accessible from the standby even when the master is down, i.e. it should
reside on the standby server itself or another trusted server, not on reside on the standby server itself or another trusted server, not on
the master server. the master server.
@ -676,7 +676,7 @@ protocol to make nodes agree on a serializable transactional order.
</para> </para>
<para> <para>
Take a base backup as described in <xref linkend="backup-base-backup"> Take a base backup as described in <xref linkend="backup-base-backup"/>
to bootstrap the standby server. to bootstrap the standby server.
</para> </para>
</sect2> </sect2>
@ -686,7 +686,7 @@ protocol to make nodes agree on a serializable transactional order.
<para> <para>
To set up the standby server, restore the base backup taken from primary To set up the standby server, restore the base backup taken from primary
server (see <xref linkend="backup-pitr-recovery">). Create a recovery server (see <xref linkend="backup-pitr-recovery"/>). Create a recovery
command file <filename>recovery.conf</filename> in the standby's cluster data command file <filename>recovery.conf</filename> in the standby's cluster data
directory, and turn on <varname>standby_mode</varname>. Set directory, and turn on <varname>standby_mode</varname>. Set
<varname>restore_command</varname> to a simple command to copy files from <varname>restore_command</varname> to a simple command to copy files from
@ -701,7 +701,7 @@ protocol to make nodes agree on a serializable transactional order.
Do not use pg_standby or similar tools with the built-in standby mode Do not use pg_standby or similar tools with the built-in standby mode
described here. <varname>restore_command</varname> should return immediately described here. <varname>restore_command</varname> should return immediately
if the file does not exist; the server will retry the command again if if the file does not exist; the server will retry the command again if
necessary. See <xref linkend="log-shipping-alternative"> necessary. See <xref linkend="log-shipping-alternative"/>
for using tools like pg_standby. for using tools like pg_standby.
</para> </para>
</note> </note>
@ -724,11 +724,11 @@ protocol to make nodes agree on a serializable transactional order.
<para> <para>
If you're using a WAL archive, its size can be minimized using the <xref If you're using a WAL archive, its size can be minimized using the <xref
linkend="archive-cleanup-command"> parameter to remove files that are no linkend="archive-cleanup-command"/> parameter to remove files that are no
longer required by the standby server. longer required by the standby server.
The <application>pg_archivecleanup</application> utility is designed specifically to The <application>pg_archivecleanup</application> utility is designed specifically to
be used with <varname>archive_cleanup_command</varname> in typical single-standby be used with <varname>archive_cleanup_command</varname> in typical single-standby
configurations, see <xref linkend="pgarchivecleanup">. configurations, see <xref linkend="pgarchivecleanup"/>.
Note however, that if you're using the archive for backup purposes, you Note however, that if you're using the archive for backup purposes, you
need to retain files needed to recover from at least the latest base need to retain files needed to recover from at least the latest base
backup, even if they're no longer needed by the standby. backup, even if they're no longer needed by the standby.
@ -768,7 +768,7 @@ archive_cleanup_command = 'pg_archivecleanup /path/to/archive %r'
<para> <para>
Streaming replication is asynchronous by default Streaming replication is asynchronous by default
(see <xref linkend="synchronous-replication">), in which case there is (see <xref linkend="synchronous-replication"/>), in which case there is
a small delay between committing a transaction in the primary and the a small delay between committing a transaction in the primary and the
changes becoming visible in the standby. This delay is however much changes becoming visible in the standby. This delay is however much
smaller than with file-based log shipping, typically under one second smaller than with file-based log shipping, typically under one second
@ -791,27 +791,27 @@ archive_cleanup_command = 'pg_archivecleanup /path/to/archive %r'
<para> <para>
To use streaming replication, set up a file-based log-shipping standby To use streaming replication, set up a file-based log-shipping standby
server as described in <xref linkend="warm-standby">. The step that server as described in <xref linkend="warm-standby"/>. The step that
turns a file-based log-shipping standby into streaming replication turns a file-based log-shipping standby into streaming replication
standby is setting <varname>primary_conninfo</varname> setting in the standby is setting <varname>primary_conninfo</varname> setting in the
<filename>recovery.conf</filename> file to point to the primary server. Set <filename>recovery.conf</filename> file to point to the primary server. Set
<xref linkend="guc-listen-addresses"> and authentication options <xref linkend="guc-listen-addresses"/> and authentication options
(see <filename>pg_hba.conf</filename>) on the primary so that the standby server (see <filename>pg_hba.conf</filename>) on the primary so that the standby server
can connect to the <literal>replication</literal> pseudo-database on the primary can connect to the <literal>replication</literal> pseudo-database on the primary
server (see <xref linkend="streaming-replication-authentication">). server (see <xref linkend="streaming-replication-authentication"/>).
</para> </para>
<para> <para>
On systems that support the keepalive socket option, setting On systems that support the keepalive socket option, setting
<xref linkend="guc-tcp-keepalives-idle">, <xref linkend="guc-tcp-keepalives-idle"/>,
<xref linkend="guc-tcp-keepalives-interval"> and <xref linkend="guc-tcp-keepalives-interval"/> and
<xref linkend="guc-tcp-keepalives-count"> helps the primary promptly <xref linkend="guc-tcp-keepalives-count"/> helps the primary promptly
notice a broken connection. notice a broken connection.
</para> </para>
<para> <para>
Set the maximum number of concurrent connections from the standby servers Set the maximum number of concurrent connections from the standby servers
(see <xref linkend="guc-max-wal-senders"> for details). (see <xref linkend="guc-max-wal-senders"/> for details).
</para> </para>
<para> <para>
@ -882,15 +882,15 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
standby. These locations can be retrieved using standby. These locations can be retrieved using
<function>pg_current_wal_lsn</function> on the primary and <function>pg_current_wal_lsn</function> on the primary and
<function>pg_last_wal_receive_lsn</function> on the standby, <function>pg_last_wal_receive_lsn</function> on the standby,
respectively (see <xref linkend="functions-admin-backup-table"> and respectively (see <xref linkend="functions-admin-backup-table"/> and
<xref linkend="functions-recovery-info-table"> for details). <xref linkend="functions-recovery-info-table"/> for details).
The last WAL receive location in the standby is also displayed in the The last WAL receive location in the standby is also displayed in the
process status of the WAL receiver process, displayed using the process status of the WAL receiver process, displayed using the
<command>ps</command> command (see <xref linkend="monitoring-ps"> for details). <command>ps</command> command (see <xref linkend="monitoring-ps"/> for details).
</para> </para>
<para> <para>
You can retrieve a list of WAL sender processes via the You can retrieve a list of WAL sender processes via the
<xref linkend="pg-stat-replication-view"> view. Large differences between <xref linkend="pg-stat-replication-view"/> view. Large differences between
<function>pg_current_wal_lsn</function> and the view's <literal>sent_lsn</literal> field <function>pg_current_wal_lsn</function> and the view's <literal>sent_lsn</literal> field
might indicate that the master server is under heavy load, while might indicate that the master server is under heavy load, while
differences between <literal>sent_lsn</literal> and differences between <literal>sent_lsn</literal> and
@ -899,7 +899,7 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
</para> </para>
<para> <para>
On a hot standby, the status of the WAL receiver process can be retrieved On a hot standby, the status of the WAL receiver process can be retrieved
via the <xref linkend="pg-stat-wal-receiver-view"> view. A large via the <xref linkend="pg-stat-wal-receiver-view"/> view. A large
difference between <function>pg_last_wal_replay_lsn</function> and the difference between <function>pg_last_wal_replay_lsn</function> and the
view's <literal>received_lsn</literal> indicates that WAL is being view's <literal>received_lsn</literal> indicates that WAL is being
received faster than it can be replayed. received faster than it can be replayed.
@ -922,9 +922,9 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
</para> </para>
<para> <para>
In lieu of using replication slots, it is possible to prevent the removal In lieu of using replication slots, it is possible to prevent the removal
of old WAL segments using <xref linkend="guc-wal-keep-segments">, or by of old WAL segments using <xref linkend="guc-wal-keep-segments"/>, or by
storing the segments in an archive using storing the segments in an archive using
<xref linkend="guc-archive-command">. <xref linkend="guc-archive-command"/>.
However, these methods often result in retaining more WAL segments than However, these methods often result in retaining more WAL segments than
required, whereas replication slots retain only the number of segments required, whereas replication slots retain only the number of segments
known to be needed. An advantage of these methods is that they bound known to be needed. An advantage of these methods is that they bound
@ -932,8 +932,8 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
to do this using replication slots. to do this using replication slots.
</para> </para>
<para> <para>
Similarly, <xref linkend="guc-hot-standby-feedback"> Similarly, <xref linkend="guc-hot-standby-feedback"/>
and <xref linkend="guc-vacuum-defer-cleanup-age"> provide protection against and <xref linkend="guc-vacuum-defer-cleanup-age"/> provide protection against
relevant rows being removed by vacuum, but the former provides no relevant rows being removed by vacuum, but the former provides no
protection during any time period when the standby is not connected, protection during any time period when the standby is not connected,
and the latter often needs to be set to a high value to provide adequate and the latter often needs to be set to a high value to provide adequate
@ -952,8 +952,8 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
</para> </para>
<para> <para>
Slots can be created and dropped either via the streaming replication Slots can be created and dropped either via the streaming replication
protocol (see <xref linkend="protocol-replication">) or via SQL protocol (see <xref linkend="protocol-replication"/>) or via SQL
functions (see <xref linkend="functions-replication">). functions (see <xref linkend="functions-replication"/>).
</para> </para>
</sect3> </sect3>
<sect3 id="streaming-replication-slots-config"> <sect3 id="streaming-replication-slots-config">
@ -1017,7 +1017,7 @@ primary_slot_name = 'node_a_slot'
<para> <para>
Cascading replication is currently asynchronous. Synchronous replication Cascading replication is currently asynchronous. Synchronous replication
(see <xref linkend="synchronous-replication">) settings have no effect on (see <xref linkend="synchronous-replication"/>) settings have no effect on
cascading replication at present. cascading replication at present.
</para> </para>
@ -1034,7 +1034,7 @@ primary_slot_name = 'node_a_slot'
<para> <para>
To use cascading replication, set up the cascading standby so that it can To use cascading replication, set up the cascading standby so that it can
accept replication connections (that is, set accept replication connections (that is, set
<xref linkend="guc-max-wal-senders"> and <xref linkend="guc-hot-standby">, <xref linkend="guc-max-wal-senders"/> and <xref linkend="guc-hot-standby"/>,
and configure and configure
<link linkend="auth-pg-hba-conf">host-based authentication</link>). <link linkend="auth-pg-hba-conf">host-based authentication</link>).
You will also need to set <varname>primary_conninfo</varname> in the downstream You will also need to set <varname>primary_conninfo</varname> in the downstream
@ -1109,11 +1109,11 @@ primary_slot_name = 'node_a_slot'
<para> <para>
Once streaming replication has been configured, configuring synchronous Once streaming replication has been configured, configuring synchronous
replication requires only one additional configuration step: replication requires only one additional configuration step:
<xref linkend="guc-synchronous-standby-names"> must be set to <xref linkend="guc-synchronous-standby-names"/> must be set to
a non-empty value. <varname>synchronous_commit</varname> must also be set to a non-empty value. <varname>synchronous_commit</varname> must also be set to
<literal>on</literal>, but since this is the default value, typically no change is <literal>on</literal>, but since this is the default value, typically no change is
required. (See <xref linkend="runtime-config-wal-settings"> and required. (See <xref linkend="runtime-config-wal-settings"/> and
<xref linkend="runtime-config-replication-master">.) <xref linkend="runtime-config-replication-master"/>.)
This configuration will cause each commit to wait for This configuration will cause each commit to wait for
confirmation that the standby has written the commit record to durable confirmation that the standby has written the commit record to durable
storage. storage.
@ -1451,7 +1451,7 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
and might stay down. To return to normal operation, a standby server and might stay down. To return to normal operation, a standby server
must be recreated, must be recreated,
either on the former primary system when it comes up, or on a third, either on the former primary system when it comes up, or on a third,
possibly new, system. The <xref linkend="app-pgrewind"> utility can be possibly new, system. The <xref linkend="app-pgrewind"/> utility can be
used to speed up this process on large clusters. used to speed up this process on large clusters.
Once complete, the primary and standby can be Once complete, the primary and standby can be
considered to have switched roles. Some people choose to use a third considered to have switched roles. Some people choose to use a third
@ -1491,7 +1491,7 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
This was the only option available in versions 8.4 and below. In this This was the only option available in versions 8.4 and below. In this
setup, set <varname>standby_mode</varname> off, because you are implementing setup, set <varname>standby_mode</varname> off, because you are implementing
the polling required for standby operation yourself. See the the polling required for standby operation yourself. See the
<xref linkend="pgstandby"> module for a reference <xref linkend="pgstandby"/> module for a reference
implementation of this. implementation of this.
</para> </para>
@ -1551,7 +1551,7 @@ if (!triggered)
<para> <para>
A working example of a waiting <varname>restore_command</varname> is provided A working example of a waiting <varname>restore_command</varname> is provided
in the <xref linkend="pgstandby"> module. It in the <xref linkend="pgstandby"/> module. It
should be used as a reference on how to correctly implement the logic should be used as a reference on how to correctly implement the logic
described above. It can also be extended as needed to support specific described above. It can also be extended as needed to support specific
configurations and environments. configurations and environments.
@ -1592,17 +1592,17 @@ if (!triggered)
<para> <para>
Set up continuous archiving from the primary to a WAL archive Set up continuous archiving from the primary to a WAL archive
directory on the standby server. Ensure that directory on the standby server. Ensure that
<xref linkend="guc-archive-mode">, <xref linkend="guc-archive-mode"/>,
<xref linkend="guc-archive-command"> and <xref linkend="guc-archive-command"/> and
<xref linkend="guc-archive-timeout"> <xref linkend="guc-archive-timeout"/>
are set appropriately on the primary are set appropriately on the primary
(see <xref linkend="backup-archiving-wal">). (see <xref linkend="backup-archiving-wal"/>).
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Make a base backup of the primary server (see <xref Make a base backup of the primary server (see <xref
linkend="backup-base-backup">), and load this data onto the standby. linkend="backup-base-backup"/>), and load this data onto the standby.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -1610,7 +1610,7 @@ if (!triggered)
Begin recovery on the standby server from the local WAL Begin recovery on the standby server from the local WAL
archive, using a <filename>recovery.conf</filename> that specifies a archive, using a <filename>recovery.conf</filename> that specifies a
<varname>restore_command</varname> that waits as described <varname>restore_command</varname> that waits as described
previously (see <xref linkend="backup-pitr-recovery">). previously (see <xref linkend="backup-pitr-recovery"/>).
</para> </para>
</listitem> </listitem>
</orderedlist> </orderedlist>
@ -1644,7 +1644,7 @@ if (!triggered)
<para> <para>
An external program can call the <function>pg_walfile_name_offset()</function> An external program can call the <function>pg_walfile_name_offset()</function>
function (see <xref linkend="functions-admin">) function (see <xref linkend="functions-admin"/>)
to find out the file name and the exact byte offset within it of 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 the current end of WAL. It can then access the WAL file directly
and copy the data from the last known end of WAL through the current end and copy the data from the last known end of WAL through the current end
@ -1663,7 +1663,7 @@ if (!triggered)
<para> <para>
Starting with <productname>PostgreSQL</productname> version 9.0, you can use Starting with <productname>PostgreSQL</productname> version 9.0, you can use
streaming replication (see <xref linkend="streaming-replication">) to streaming replication (see <xref linkend="streaming-replication"/>) to
achieve the same benefits with less effort. achieve the same benefits with less effort.
</para> </para>
</sect2> </sect2>
@ -1697,7 +1697,7 @@ if (!triggered)
<title>User's Overview</title> <title>User's Overview</title>
<para> <para>
When the <xref linkend="guc-hot-standby"> parameter is set to true on a When the <xref linkend="guc-hot-standby"/> parameter is set to true on a
standby server, it will begin accepting connections once the recovery has standby server, it will begin accepting connections once the recovery has
brought the system to a consistent state. All such connections are brought the system to a consistent state. All such connections are
strictly read-only; not even temporary tables may be written. strictly read-only; not even temporary tables may be written.
@ -1713,7 +1713,7 @@ if (!triggered)
made by that transaction will be visible to any new snapshots taken on made by that transaction will be visible to any new snapshots taken on
the standby. Snapshots may be taken at the start of each query or at the the standby. Snapshots may be taken at the start of each query or at the
start of each transaction, depending on the current transaction isolation start of each transaction, depending on the current transaction isolation
level. For more details, see <xref linkend="transaction-iso">. level. For more details, see <xref linkend="transaction-iso"/>.
</para> </para>
<para> <para>
@ -1891,7 +1891,7 @@ if (!triggered)
<para> <para>
Users will be able to tell whether their session is read-only by Users will be able to tell whether their session is read-only by
issuing <command>SHOW transaction_read_only</command>. In addition, a set of issuing <command>SHOW transaction_read_only</command>. In addition, a set of
functions (<xref linkend="functions-recovery-info-table">) allow users to functions (<xref linkend="functions-recovery-info-table"/>) allow users to
access information about the standby server. These allow you to write access information about the standby server. These allow you to write
programs that are aware of the current state of the database. These programs that are aware of the current state of the database. These
can be used to monitor the progress of recovery, or to allow you to can be used to monitor the progress of recovery, or to allow you to
@ -1986,8 +1986,8 @@ if (!triggered)
When a conflicting query is short, it's typically desirable to allow it to When a conflicting query is short, it's typically desirable to allow it to
complete by delaying WAL application for a little bit; but a long delay in complete by delaying WAL application for a little bit; but a long delay in
WAL application is usually not desirable. So the cancel mechanism has WAL application is usually not desirable. So the cancel mechanism has
parameters, <xref linkend="guc-max-standby-archive-delay"> and <xref parameters, <xref linkend="guc-max-standby-archive-delay"/> and <xref
linkend="guc-max-standby-streaming-delay">, that define the maximum linkend="guc-max-standby-streaming-delay"/>, that define the maximum
allowed delay in WAL application. Conflicting queries will be canceled allowed delay in WAL application. Conflicting queries will be canceled
once it has taken longer than the relevant delay setting to apply any once it has taken longer than the relevant delay setting to apply any
newly-received WAL data. There are two parameters so that different delay newly-received WAL data. There are two parameters so that different delay
@ -2082,7 +2082,7 @@ if (!triggered)
</para> </para>
<para> <para>
Another option is to increase <xref linkend="guc-vacuum-defer-cleanup-age"> Another option is to increase <xref linkend="guc-vacuum-defer-cleanup-age"/>
on the primary server, so that dead rows will not be cleaned up as quickly on the primary server, so that dead rows will not be cleaned up as quickly
as they normally would be. This will allow more time for queries to as they normally would be. This will allow more time for queries to
execute before they are canceled on the standby, without having to set execute before they are canceled on the standby, without having to set
@ -2189,8 +2189,8 @@ LOG: database system is ready to accept read only connections
<para> <para>
It is important that the administrator select appropriate settings for It is important that the administrator select appropriate settings for
<xref linkend="guc-max-standby-archive-delay"> and <xref <xref linkend="guc-max-standby-archive-delay"/> and <xref
linkend="guc-max-standby-streaming-delay">. The best choices vary linkend="guc-max-standby-streaming-delay"/>. The best choices vary
depending on business priorities. For example if the server is primarily depending on business priorities. For example if the server is primarily
tasked as a High Availability server, then you will want low delay tasked as a High Availability server, then you will want low delay
settings, perhaps even zero, though that is a very aggressive setting. If settings, perhaps even zero, though that is a very aggressive setting. If
@ -2382,23 +2382,23 @@ LOG: database system is ready to accept read only connections
<para> <para>
Various parameters have been mentioned above in Various parameters have been mentioned above in
<xref linkend="hot-standby-conflict"> and <xref linkend="hot-standby-conflict"/> and
<xref linkend="hot-standby-admin">. <xref linkend="hot-standby-admin"/>.
</para> </para>
<para> <para>
On the primary, parameters <xref linkend="guc-wal-level"> and On the primary, parameters <xref linkend="guc-wal-level"/> and
<xref linkend="guc-vacuum-defer-cleanup-age"> can be used. <xref linkend="guc-vacuum-defer-cleanup-age"/> can be used.
<xref linkend="guc-max-standby-archive-delay"> and <xref linkend="guc-max-standby-archive-delay"/> and
<xref linkend="guc-max-standby-streaming-delay"> have no effect if set on <xref linkend="guc-max-standby-streaming-delay"/> have no effect if set on
the primary. the primary.
</para> </para>
<para> <para>
On the standby, parameters <xref linkend="guc-hot-standby">, On the standby, parameters <xref linkend="guc-hot-standby"/>,
<xref linkend="guc-max-standby-archive-delay"> and <xref linkend="guc-max-standby-archive-delay"/> and
<xref linkend="guc-max-standby-streaming-delay"> can be used. <xref linkend="guc-max-standby-streaming-delay"/> can be used.
<xref linkend="guc-vacuum-defer-cleanup-age"> has no effect <xref linkend="guc-vacuum-defer-cleanup-age"/> has no effect
as long as the server remains in standby mode, though it will as long as the server remains in standby mode, though it will
become relevant if the standby becomes primary. become relevant if the standby becomes primary.
</para> </para>
@ -2452,8 +2452,8 @@ LOG: database system is ready to accept read only connections
<listitem> <listitem>
<para> <para>
The Serializable transaction isolation level is not yet available in hot The Serializable transaction isolation level is not yet available in hot
standby. (See <xref linkend="xact-serializable"> and standby. (See <xref linkend="xact-serializable"/> and
<xref linkend="serializable-consistency"> for details.) <xref linkend="serializable-consistency"/> for details.)
An attempt to set a transaction to the serializable isolation level in An attempt to set a transaction to the serializable isolation level in
hot standby mode will generate an error. hot standby mode will generate an error.
</para> </para>

16
doc/src/sgml/history.sgml
View File

@ -31,12 +31,12 @@
Office (<acronym>ARO</acronym>), the National Science Foundation Office (<acronym>ARO</acronym>), the National Science Foundation
(<acronym>NSF</acronym>), and ESL, Inc. The implementation of (<acronym>NSF</acronym>), and ESL, Inc. The implementation of
<productname>POSTGRES</productname> began in 1986. The initial <productname>POSTGRES</productname> began in 1986. The initial
concepts for the system were presented in <xref linkend="ston86">, concepts for the system were presented in <xref linkend="ston86"/>,
and the definition of the initial data model appeared in <xref and the definition of the initial data model appeared in <xref
linkend="rowe87">. The design of the rule system at that time was linkend="rowe87"/>. The design of the rule system at that time was
described in <xref linkend="ston87a">. The rationale and described in <xref linkend="ston87a"/>. The rationale and
architecture of the storage manager were detailed in <xref architecture of the storage manager were detailed in <xref
linkend="ston87b">. linkend="ston87b"/>.
</para> </para>
<para> <para>
@ -44,10 +44,10 @@
releases since then. The first <quote>demoware</quote> system releases since then. The first <quote>demoware</quote> system
became operational in 1987 and was shown at the 1988 became operational in 1987 and was shown at the 1988
<acronym>ACM-SIGMOD</acronym> Conference. Version 1, described in <acronym>ACM-SIGMOD</acronym> Conference. Version 1, described in
<xref linkend="ston90a">, was released to a few external users in <xref linkend="ston90a"/>, was released to a few external users in
June 1989. In response to a critique of the first rule system June 1989. In response to a critique of the first rule system
(<xref linkend="ston89">), the rule system was redesigned (<xref (<xref linkend="ston89"/>), the rule system was redesigned (<xref
linkend="ston90b">), and Version 2 was released in June 1990 with linkend="ston90b"/>), and Version 2 was released in June 1990 with
the new rule system. Version 3 appeared in 1991 and added support the new rule system. Version 3 appeared in 1991 and added support
for multiple storage managers, an improved query executor, and a for multiple storage managers, an improved query executor, and a
rewritten rule system. For the most part, subsequent releases rewritten rule system. For the most part, subsequent releases
@ -216,7 +216,7 @@
<para> <para>
Details about what has happened in <productname>PostgreSQL</productname> since Details about what has happened in <productname>PostgreSQL</productname> since
then can be found in <xref linkend="release">. then can be found in <xref linkend="release"/>.
</para> </para>
</sect2> </sect2>
</sect1> </sect1>

8
doc/src/sgml/hstore.sgml
View File

@ -70,7 +70,7 @@ key =&gt; NULL
constant, then any single-quote characters and (depending on the setting of constant, then any single-quote characters and (depending on the setting of
the <varname>standard_conforming_strings</varname> configuration parameter) the <varname>standard_conforming_strings</varname> configuration parameter)
backslash characters need to be escaped correctly. See backslash characters need to be escaped correctly. See
<xref linkend="sql-syntax-strings"> for more on the handling of string <xref linkend="sql-syntax-strings"/> for more on the handling of string
constants. constants.
</para> </para>
</note> </note>
@ -87,8 +87,8 @@ key =&gt; NULL
<para> <para>
The operators provided by the <literal>hstore</literal> module are The operators provided by the <literal>hstore</literal> module are
shown in <xref linkend="hstore-op-table">, the functions shown in <xref linkend="hstore-op-table"/>, the functions
in <xref linkend="hstore-func-table">. in <xref linkend="hstore-func-table"/>.
</para> </para>
<table id="hstore-op-table"> <table id="hstore-op-table">
@ -629,7 +629,7 @@ ALTER TABLE tablename ALTER hstorecol TYPE hstore USING hstorecol || '';
extensions for PL/Python are extensions for PL/Python are
called <literal>hstore_plpythonu</literal>, <literal>hstore_plpython2u</literal>, called <literal>hstore_plpythonu</literal>, <literal>hstore_plpython2u</literal>,
and <literal>hstore_plpython3u</literal> and <literal>hstore_plpython3u</literal>
(see <xref linkend="plpython-python23"> for the PL/Python naming (see <xref linkend="plpython-python23"/> for the PL/Python naming
convention). If you use them, <type>hstore</type> values are mapped to convention). If you use them, <type>hstore</type> values are mapped to
Python dictionaries. Python dictionaries.
</para> </para>

26
doc/src/sgml/indexam.sgml
View File

@ -22,7 +22,7 @@
pages so that they can use the regular storage manager and buffer manager pages so that they can use the regular storage manager and buffer manager
to access the index contents. (All the existing index access methods to access the index contents. (All the existing index access methods
furthermore use the standard page layout described in <xref furthermore use the standard page layout described in <xref
linkend="storage-page-layout">, and most use the same format for index linkend="storage-page-layout"/>, and most use the same format for index
tuple headers; but these decisions are not forced on an access method.) tuple headers; but these decisions are not forced on an access method.)
</para> </para>
@ -31,7 +31,7 @@
<firstterm>tuple identifiers</firstterm>, or <acronym>TIDs</acronym>, of row versions <firstterm>tuple identifiers</firstterm>, or <acronym>TIDs</acronym>, of row versions
(tuples) in the index's parent table. A TID consists of a (tuples) in the index's parent table. A TID consists of a
block number and an item number within that block (see <xref block number and an item number within that block (see <xref
linkend="storage-page-layout">). This is sufficient linkend="storage-page-layout"/>). This is sufficient
information to fetch a particular row version from the table. information to fetch a particular row version from the table.
Indexes are not directly aware that under MVCC, there might be multiple Indexes are not directly aware that under MVCC, there might be multiple
extant versions of the same logical row; to an index, each tuple is extant versions of the same logical row; to an index, each tuple is
@ -52,8 +52,8 @@
system catalog. The <structname>pg_am</structname> entry system catalog. The <structname>pg_am</structname> entry
specifies a name and a <firstterm>handler function</firstterm> for the access specifies a name and a <firstterm>handler function</firstterm> for the access
method. These entries can be created and deleted using the method. These entries can be created and deleted using the
<xref linkend="sql-create-access-method"> and <xref linkend="sql-create-access-method"/> and
<xref linkend="sql-drop-access-method"> SQL commands. <xref linkend="sql-drop-access-method"/> SQL commands.
</para> </para>
<para> <para>
@ -71,7 +71,7 @@
functions for the access method, which do all of the real work to access functions for the access method, which do all of the real work to access
indexes. These support functions are plain C functions and are not indexes. These support functions are plain C functions and are not
visible or callable at the SQL level. The support functions are described visible or callable at the SQL level. The support functions are described
in <xref linkend="index-functions">. in <xref linkend="index-functions"/>.
</para> </para>
<para> <para>
@ -153,7 +153,7 @@ typedef struct IndexAmRoutine
These entries allow the planner These entries allow the planner
to determine what kinds of query qualifications can be used with to determine what kinds of query qualifications can be used with
indexes of this access method. Operator families and classes are described indexes of this access method. Operator families and classes are described
in <xref linkend="xindex">, which is prerequisite material for reading in <xref linkend="xindex"/>, which is prerequisite material for reading
this chapter. this chapter.
</para> </para>
@ -177,7 +177,7 @@ typedef struct IndexAmRoutine
<para> <para>
Some of the flag fields of <structname>IndexAmRoutine</structname> have nonobvious Some of the flag fields of <structname>IndexAmRoutine</structname> have nonobvious
implications. The requirements of <structfield>amcanunique</structfield> implications. The requirements of <structfield>amcanunique</structfield>
are discussed in <xref linkend="index-unique-checks">. are discussed in <xref linkend="index-unique-checks"/>.
The <structfield>amcanmulticol</structfield> flag asserts that the The <structfield>amcanmulticol</structfield> flag asserts that the
access method supports multicolumn indexes, while access method supports multicolumn indexes, while
<structfield>amoptionalkey</structfield> asserts that it allows scans <structfield>amoptionalkey</structfield> asserts that it allows scans
@ -271,7 +271,7 @@ aminsert (Relation indexRelation,
<structfield>amcanunique</structfield> flag is true) then <structfield>amcanunique</structfield> flag is true) then
<literal>checkUnique</literal> indicates the type of uniqueness check to <literal>checkUnique</literal> indicates the type of uniqueness check to
perform. This varies depending on whether the unique constraint is perform. This varies depending on whether the unique constraint is
deferrable; see <xref linkend="index-unique-checks"> for details. deferrable; see <xref linkend="index-unique-checks"/> for details.
Normally the access method only needs the <literal>heapRelation</literal> Normally the access method only needs the <literal>heapRelation</literal>
parameter when performing uniqueness checking (since then it will have to parameter when performing uniqueness checking (since then it will have to
look into the heap to verify tuple liveness). look into the heap to verify tuple liveness).
@ -386,7 +386,7 @@ amcostestimate (PlannerInfo *root,
double *indexCorrelation); double *indexCorrelation);
</programlisting> </programlisting>
Estimate the costs of an index scan. This function is described fully Estimate the costs of an index scan. This function is described fully
in <xref linkend="index-cost-estimation">, below. in <xref linkend="index-cost-estimation"/>, below.
</para> </para>
<para> <para>
@ -480,7 +480,7 @@ amvalidate (Oid opclassoid);
The purpose of an index, of course, is to support scans for tuples matching The purpose of an index, of course, is to support scans for tuples matching
an indexable <literal>WHERE</literal> condition, often called a an indexable <literal>WHERE</literal> condition, often called a
<firstterm>qualifier</firstterm> or <firstterm>scan key</firstterm>. The semantics of <firstterm>qualifier</firstterm> or <firstterm>scan key</firstterm>. The semantics of
index scanning are described more fully in <xref linkend="index-scanning">, index scanning are described more fully in <xref linkend="index-scanning"/>,
below. An index access method can support <quote>plain</quote> index scans, below. An index access method can support <quote>plain</quote> index scans,
<quote>bitmap</quote> index scans, or both. The scan-related functions that an <quote>bitmap</quote> index scans, or both. The scan-related functions that an
index access method must or may provide are: index access method must or may provide are:
@ -594,7 +594,7 @@ amgetbitmap (IndexScanDesc scan,
<function>amgetbitmap</function> and <function>amgetbitmap</function> and
<function>amgettuple</function> cannot be used in the same index scan; there <function>amgettuple</function> cannot be used in the same index scan; there
are other restrictions too when using <function>amgetbitmap</function>, as explained are other restrictions too when using <function>amgetbitmap</function>, as explained
in <xref linkend="index-scanning">. in <xref linkend="index-scanning"/>.
</para> </para>
<para> <para>
@ -852,7 +852,7 @@ amparallelrescan (IndexScanDesc scan);
index tuples. index tuples.
Finally, <function>amgetbitmap</function> Finally, <function>amgetbitmap</function>
does not guarantee any locking of the returned tuples, with implications does not guarantee any locking of the returned tuples, with implications
spelled out in <xref linkend="index-locking">. spelled out in <xref linkend="index-locking"/>.
</para> </para>
<para> <para>
@ -901,7 +901,7 @@ amparallelrescan (IndexScanDesc scan);
A new heap entry is made before making its index entries. (Therefore A new heap entry is made before making its index entries. (Therefore
a concurrent index scan is likely to fail to see the heap entry. a concurrent index scan is likely to fail to see the heap entry.
This is okay because the index reader would be uninterested in an This is okay because the index reader would be uninterested in an
uncommitted row anyway. But see <xref linkend="index-unique-checks">.) uncommitted row anyway. But see <xref linkend="index-unique-checks"/>.)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>

72
doc/src/sgml/indices.sgml
View File

@ -77,7 +77,7 @@ CREATE INDEX test1_id_index ON test1 (id);
than a sequential table scan. But you might have to run the than a sequential table scan. But you might have to run the
<command>ANALYZE</command> command regularly to update <command>ANALYZE</command> command regularly to update
statistics to allow the query planner to make educated decisions. statistics to allow the query planner to make educated decisions.
See <xref linkend="performance-tips"> for information about See <xref linkend="performance-tips"/> for information about
how to find out whether an index is used and when and why the how to find out whether an index is used and when and why the
planner might choose <emphasis>not</emphasis> to use an index. planner might choose <emphasis>not</emphasis> to use an index.
</para> </para>
@ -99,7 +99,7 @@ CREATE INDEX test1_id_index ON test1 (id);
It is possible to allow writes to occur in parallel with index It is possible to allow writes to occur in parallel with index
creation, but there are several caveats to be aware of &mdash; creation, but there are several caveats to be aware of &mdash;
for more information see <xref linkend="sql-createindex-concurrently" for more information see <xref linkend="sql-createindex-concurrently"
endterm="sql-createindex-concurrently-title">. endterm="sql-createindex-concurrently-title"/>.
</para> </para>
<para> <para>
@ -161,7 +161,7 @@ CREATE INDEX test1_id_index ON test1 (id);
<literal>col LIKE '%bar'</literal>. However, if your database does not <literal>col LIKE '%bar'</literal>. However, if your database does not
use the C locale you will need to create the index with a special use the C locale you will need to create the index with a special
operator class to support indexing of pattern-matching queries; see operator class to support indexing of pattern-matching queries; see
<xref linkend="indexes-opclass"> below. It is also possible to use <xref linkend="indexes-opclass"/> below. It is also possible to use
B-tree indexes for <literal>ILIKE</literal> and B-tree indexes for <literal>ILIKE</literal> and
<literal>~*</literal>, but only if the pattern starts with <literal>~*</literal>, but only if the pattern starts with
non-alphabetic characters, i.e., characters that are not affected by non-alphabetic characters, i.e., characters that are not affected by
@ -226,13 +226,13 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable>
<member><literal>&amp;&amp;</literal></member> <member><literal>&amp;&amp;</literal></member>
</simplelist> </simplelist>
(See <xref linkend="functions-geometry"> for the meaning of (See <xref linkend="functions-geometry"/> for the meaning of
these operators.) these operators.)
The GiST operator classes included in the standard distribution are The GiST operator classes included in the standard distribution are
documented in <xref linkend="gist-builtin-opclasses-table">. documented in <xref linkend="gist-builtin-opclasses-table"/>.
Many other GiST operator Many other GiST operator
classes are available in the <literal>contrib</literal> collection or as separate classes are available in the <literal>contrib</literal> collection or as separate
projects. For more information see <xref linkend="gist">. projects. For more information see <xref linkend="gist"/>.
</para> </para>
<para> <para>
@ -244,7 +244,7 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
</programlisting> </programlisting>
which finds the ten places closest to a given target point. The ability which finds the ten places closest to a given target point. The ability
to do this is again dependent on the particular operator class being used. to do this is again dependent on the particular operator class being used.
In <xref linkend="gist-builtin-opclasses-table">, operators that can be In <xref linkend="gist-builtin-opclasses-table"/>, operators that can be
used in this way are listed in the column <quote>Ordering Operators</quote>. used in this way are listed in the column <quote>Ordering Operators</quote>.
</para> </para>
@ -274,11 +274,11 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
<member><literal>&gt;^</literal></member> <member><literal>&gt;^</literal></member>
</simplelist> </simplelist>
(See <xref linkend="functions-geometry"> for the meaning of (See <xref linkend="functions-geometry"/> for the meaning of
these operators.) these operators.)
The SP-GiST operator classes included in the standard distribution are The SP-GiST operator classes included in the standard distribution are
documented in <xref linkend="spgist-builtin-opclasses-table">. documented in <xref linkend="spgist-builtin-opclasses-table"/>.
For more information see <xref linkend="spgist">. For more information see <xref linkend="spgist"/>.
</para> </para>
<para> <para>
@ -313,13 +313,13 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
<member><literal>&amp;&amp;</literal></member> <member><literal>&amp;&amp;</literal></member>
</simplelist> </simplelist>
(See <xref linkend="functions-array"> for the meaning of (See <xref linkend="functions-array"/> for the meaning of
these operators.) these operators.)
The GIN operator classes included in the standard distribution are The GIN operator classes included in the standard distribution are
documented in <xref linkend="gin-builtin-opclasses-table">. documented in <xref linkend="gin-builtin-opclasses-table"/>.
Many other GIN operator Many other GIN operator
classes are available in the <literal>contrib</literal> collection or as separate classes are available in the <literal>contrib</literal> collection or as separate
projects. For more information see <xref linkend="gin">. projects. For more information see <xref linkend="gin"/>.
</para> </para>
<para> <para>
@ -351,8 +351,8 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
</simplelist> </simplelist>
The BRIN operator classes included in the standard distribution are The BRIN operator classes included in the standard distribution are
documented in <xref linkend="brin-builtin-opclasses-table">. documented in <xref linkend="brin-builtin-opclasses-table"/>.
For more information see <xref linkend="brin">. For more information see <xref linkend="brin"/>.
</para> </para>
</sect1> </sect1>
@ -454,8 +454,8 @@ CREATE INDEX test2_mm_idx ON test2 (major, minor);
an index on a single column is sufficient and saves space and time. an index on a single column is sufficient and saves space and time.
Indexes with more than three columns are unlikely to be helpful Indexes with more than three columns are unlikely to be helpful
unless the usage of the table is extremely stylized. See also unless the usage of the table is extremely stylized. See also
<xref linkend="indexes-bitmap-scans"> and <xref linkend="indexes-bitmap-scans"/> and
<xref linkend="indexes-index-only-scans"> for some discussion of the <xref linkend="indexes-index-only-scans"/> for some discussion of the
merits of different index configurations. merits of different index configurations.
</para> </para>
</sect1> </sect1>
@ -609,7 +609,7 @@ CREATE INDEX test3_desc_index ON test3 (id DESC NULLS LAST);
process the queries that use both columns. You could also create a process the queries that use both columns. You could also create a
multicolumn index on <literal>(x, y)</literal>. This index would typically be multicolumn index on <literal>(x, y)</literal>. This index would typically be
more efficient than index combination for queries involving both more efficient than index combination for queries involving both
columns, but as discussed in <xref linkend="indexes-multicolumn">, it columns, but as discussed in <xref linkend="indexes-multicolumn"/>, it
would be almost useless for queries involving only <literal>y</literal>, so it would be almost useless for queries involving only <literal>y</literal>, so it
should not be the only index. A combination of the multicolumn index should not be the only index. A combination of the multicolumn index
and a separate index on <literal>y</literal> would serve reasonably well. For and a separate index on <literal>y</literal> would serve reasonably well. For
@ -762,7 +762,7 @@ CREATE INDEX people_names ON people ((first_name || ' ' || last_name));
index at all. This reduces the size of the index, which will speed index at all. This reduces the size of the index, which will speed
up those queries that do use the index. It will also speed up many table up those queries that do use the index. It will also speed up many table
update operations because the index does not need to be update operations because the index does not need to be
updated in all cases. <xref linkend="indexes-partial-ex1"> shows a updated in all cases. <xref linkend="indexes-partial-ex1"/> shows a
possible application of this idea. possible application of this idea.
</para> </para>
@ -827,7 +827,7 @@ WHERE client_ip = inet '192.168.100.23';
Another possible use for a partial index is to exclude values from the Another possible use for a partial index is to exclude values from the
index that the index that the
typical query workload is not interested in; this is shown in <xref typical query workload is not interested in; this is shown in <xref
linkend="indexes-partial-ex2">. This results in the same linkend="indexes-partial-ex2"/>. This results in the same
advantages as listed above, but it prevents the advantages as listed above, but it prevents the
<quote>uninteresting</quote> values from being accessed via that <quote>uninteresting</quote> values from being accessed via that
index, even if an index scan might be profitable in that index, even if an index scan might be profitable in that
@ -878,7 +878,7 @@ SELECT * FROM orders WHERE order_nr = 3501;
</example> </example>
<para> <para>
<xref linkend="indexes-partial-ex2"> also illustrates that the <xref linkend="indexes-partial-ex2"/> also illustrates that the
indexed column and the column used in the predicate do not need to indexed column and the column used in the predicate do not need to
match. <productname>PostgreSQL</productname> supports partial match. <productname>PostgreSQL</productname> supports partial
indexes with arbitrary predicates, so long as only columns of the indexes with arbitrary predicates, so long as only columns of the
@ -909,7 +909,7 @@ SELECT * FROM orders WHERE order_nr = 3501;
A third possible use for partial indexes does not require the A third possible use for partial indexes does not require the
index to be used in queries at all. The idea here is to create index to be used in queries at all. The idea here is to create
a unique index over a subset of a table, as in <xref a unique index over a subset of a table, as in <xref
linkend="indexes-partial-ex3">. This enforces uniqueness linkend="indexes-partial-ex3"/>. This enforces uniqueness
among the rows that satisfy the index predicate, without constraining among the rows that satisfy the index predicate, without constraining
those that do not. those that do not.
</para> </para>
@ -962,8 +962,8 @@ CREATE UNIQUE INDEX tests_success_constraint ON tests (subject, target)
<para> <para>
More information about partial indexes can be found in <xref More information about partial indexes can be found in <xref
linkend="ston89b">, <xref linkend="olson93">, and <xref linkend="ston89b"/>, <xref linkend="olson93"/>, and <xref
linkend="seshadri95">. linkend="seshadri95"/>.
</para> </para>
</sect1> </sect1>
@ -1157,7 +1157,7 @@ CREATE INDEX test1c_content_y_index ON test1c (content COLLATE "y");
the index, the table rows they reference might be anywhere in the heap. the index, the table rows they reference might be anywhere in the heap.
The heap-access portion of an index scan thus involves a lot of random The heap-access portion of an index scan thus involves a lot of random
access into the heap, which can be slow, particularly on traditional access into the heap, which can be slow, particularly on traditional
rotating media. (As described in <xref linkend="indexes-bitmap-scans">, rotating media. (As described in <xref linkend="indexes-bitmap-scans"/>,
bitmap scans try to alleviate this cost by doing the heap accesses in bitmap scans try to alleviate this cost by doing the heap accesses in
sorted order, but that only goes so far.) sorted order, but that only goes so far.)
</para> </para>
@ -1212,7 +1212,7 @@ SELECT x FROM tab WHERE x = 'key' AND z &lt; 42;
is physically possible. But there is an additional requirement for any is physically possible. But there is an additional requirement for any
table scan in <productname>PostgreSQL</productname>: it must verify that each table scan in <productname>PostgreSQL</productname>: it must verify that each
retrieved row be <quote>visible</quote> to the query's MVCC snapshot, as retrieved row be <quote>visible</quote> to the query's MVCC snapshot, as
discussed in <xref linkend="mvcc">. Visibility information is not stored discussed in <xref linkend="mvcc"/>. Visibility information is not stored
in index entries, only in heap entries; so at first glance it would seem in index entries, only in heap entries; so at first glance it would seem
that every row retrieval would require a heap access anyway. And this is that every row retrieval would require a heap access anyway. And this is
indeed the case, if the table row has been modified recently. However, indeed the case, if the table row has been modified recently. However,
@ -1289,7 +1289,7 @@ SELECT f(x) FROM tab WHERE f(x) &lt; 1;
<para> <para>
Partial indexes also have interesting interactions with index-only scans. Partial indexes also have interesting interactions with index-only scans.
Consider the partial index shown in <xref linkend="indexes-partial-ex3">: Consider the partial index shown in <xref linkend="indexes-partial-ex3"/>:
<programlisting> <programlisting>
CREATE UNIQUE INDEX tests_success_constraint ON tests (subject, target) CREATE UNIQUE INDEX tests_success_constraint ON tests (subject, target)
WHERE success; WHERE success;
@ -1325,11 +1325,11 @@ SELECT target FROM tests WHERE subject = 'some-subject' AND success;
maintenance or tuning, it is still important to check maintenance or tuning, it is still important to check
which indexes are actually used by the real-life query workload. which indexes are actually used by the real-life query workload.
Examining index usage for an individual query is done with the Examining index usage for an individual query is done with the
<xref linkend="sql-explain"> <xref linkend="sql-explain"/>
command; its application for this purpose is command; its application for this purpose is
illustrated in <xref linkend="using-explain">. illustrated in <xref linkend="using-explain"/>.
It is also possible to gather overall statistics about index usage It is also possible to gather overall statistics about index usage
in a running server, as described in <xref linkend="monitoring-stats">. in a running server, as described in <xref linkend="monitoring-stats"/>.
</para> </para>
<para> <para>
@ -1343,7 +1343,7 @@ SELECT target FROM tests WHERE subject = 'some-subject' AND success;
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
Always run <xref linkend="sql-analyze"> Always run <xref linkend="sql-analyze"/>
first. This command first. This command
collects statistics about the distribution of the values in the collects statistics about the distribution of the values in the
table. This information is required to estimate the number of rows table. This information is required to estimate the number of rows
@ -1353,8 +1353,8 @@ SELECT target FROM tests WHERE subject = 'some-subject' AND success;
almost certain to be inaccurate. Examining an application's almost certain to be inaccurate. Examining an application's
index usage without having run <command>ANALYZE</command> is index usage without having run <command>ANALYZE</command> is
therefore a lost cause. therefore a lost cause.
See <xref linkend="vacuum-for-statistics"> See <xref linkend="vacuum-for-statistics"/>
and <xref linkend="autovacuum"> for more information. and <xref linkend="autovacuum"/> for more information.
</para> </para>
</listitem> </listitem>
@ -1386,7 +1386,7 @@ SELECT target FROM tests WHERE subject = 'some-subject' AND success;
<para> <para>
When indexes are not used, it can be useful for testing to force When indexes are not used, it can be useful for testing to force
their use. There are run-time parameters that can turn off their use. There are run-time parameters that can turn off
various plan types (see <xref linkend="runtime-config-query-enable">). various plan types (see <xref linkend="runtime-config-query-enable"/>).
For instance, turning off sequential scans For instance, turning off sequential scans
(<varname>enable_seqscan</varname>) and nested-loop joins (<varname>enable_seqscan</varname>) and nested-loop joins
(<varname>enable_nestloop</varname>), which are the most basic plans, (<varname>enable_nestloop</varname>), which are the most basic plans,
@ -1417,11 +1417,11 @@ SELECT target FROM tests WHERE subject = 'some-subject' AND success;
per-row costs of each plan node times the selectivity estimate of per-row costs of each plan node times the selectivity estimate of
the plan node. The costs estimated for the plan nodes can be adjusted the plan node. The costs estimated for the plan nodes can be adjusted
via run-time parameters (described in <xref via run-time parameters (described in <xref
linkend="runtime-config-query-constants">). linkend="runtime-config-query-constants"/>).
An inaccurate selectivity estimate is due to An inaccurate selectivity estimate is due to
insufficient statistics. It might be possible to improve this by insufficient statistics. It might be possible to improve this by
tuning the statistics-gathering parameters (see tuning the statistics-gathering parameters (see
<xref linkend="sql-altertable">). <xref linkend="sql-altertable"/>).
</para> </para>
<para> <para>

28
doc/src/sgml/information_schema.sgml
View File

@ -579,7 +579,7 @@
</table> </table>
<para> <para>
See also under <xref linkend="infoschema-columns">, a similarly See also under <xref linkend="infoschema-columns"/>, a similarly
structured view, for further information on some of the columns. structured view, for further information on some of the columns.
</para> </para>
</sect1> </sect1>
@ -776,7 +776,7 @@
<entry><literal>sql_identifier</literal></entry> <entry><literal>sql_identifier</literal></entry>
<entry> <entry>
The <quote>specific name</quote> of the function. See <xref The <quote>specific name</quote> of the function. See <xref
linkend="infoschema-routines"> for more information. linkend="infoschema-routines"/> for more information.
</entry> </entry>
</row> </row>
</tbody> </tbody>
@ -895,7 +895,7 @@
identifies which character set the available collations are identifies which character set the available collations are
applicable to. In PostgreSQL, there is only one character set per applicable to. In PostgreSQL, there is only one character set per
database (see explanation database (see explanation
in <xref linkend="infoschema-character-sets">), so this view does in <xref linkend="infoschema-character-sets"/>), so this view does
not provide much useful information. not provide much useful information.
</para> </para>
@ -1178,7 +1178,7 @@
that use data types owned by a currently enabled role. Note that in that use data types owned by a currently enabled role. Note that in
<productname>PostgreSQL</productname>, built-in data types behave <productname>PostgreSQL</productname>, built-in data types behave
like user-defined types, so they are included here as well. See like user-defined types, so they are included here as well. See
also <xref linkend="infoschema-columns"> for details. also <xref linkend="infoschema-columns"/> for details.
</para> </para>
<table> <table>
@ -3134,7 +3134,7 @@ ORDER BY c.ordinal_position;
<entry><type>sql_identifier</type></entry> <entry><type>sql_identifier</type></entry>
<entry> <entry>
The <quote>specific name</quote> of the function. See <xref The <quote>specific name</quote> of the function. See <xref
linkend="infoschema-routines"> for more information. linkend="infoschema-routines"/> for more information.
</entry> </entry>
</row> </row>
@ -3594,7 +3594,7 @@ ORDER BY c.ordinal_position;
<entry><type>sql_identifier</type></entry> <entry><type>sql_identifier</type></entry>
<entry> <entry>
The <quote>specific name</quote> of the function. See <xref The <quote>specific name</quote> of the function. See <xref
linkend="infoschema-routines"> for more information. linkend="infoschema-routines"/> for more information.
</entry> </entry>
</row> </row>
@ -3930,7 +3930,7 @@ ORDER BY c.ordinal_position;
<entry><type>sql_identifier</type></entry> <entry><type>sql_identifier</type></entry>
<entry> <entry>
The <quote>specific name</quote> of the function. See <xref The <quote>specific name</quote> of the function. See <xref
linkend="infoschema-routines"> for more information. linkend="infoschema-routines"/> for more information.
</entry> </entry>
</row> </row>
@ -4762,7 +4762,7 @@ ORDER BY c.ordinal_position;
The table <literal>sql_features</literal> contains information The table <literal>sql_features</literal> contains information
about which formal features defined in the SQL standard are about which formal features defined in the SQL standard are
supported by <productname>PostgreSQL</productname>. This is the supported by <productname>PostgreSQL</productname>. This is the
same information that is presented in <xref linkend="features">. same information that is presented in <xref linkend="features"/>.
There you can also find some additional background information. There you can also find some additional background information.
</para> </para>
@ -4998,7 +4998,7 @@ ORDER BY c.ordinal_position;
The table <literal>sql_packages</literal> contains information The table <literal>sql_packages</literal> contains information
about which feature packages defined in the SQL standard are about which feature packages defined in the SQL standard are
supported by <productname>PostgreSQL</productname>. Refer to <xref supported by <productname>PostgreSQL</productname>. Refer to <xref
linkend="features"> for background information on feature packages. linkend="features"/> for background information on feature packages.
</para> </para>
<table> <table>
@ -5586,7 +5586,7 @@ ORDER BY c.ordinal_position;
<entry><literal>sql_identifier</literal></entry> <entry><literal>sql_identifier</literal></entry>
<entry> <entry>
The <quote>specific name</quote> of the function. See <xref The <quote>specific name</quote> of the function. See <xref
linkend="infoschema-routines"> for more information. linkend="infoschema-routines"/> for more information.
</entry> </entry>
</row> </row>
@ -5891,9 +5891,9 @@ ORDER BY c.ordinal_position;
<literal>USAGE</literal> privileges granted on user-defined types to a <literal>USAGE</literal> privileges granted on user-defined types to a
currently enabled role or by a currently enabled role. There is one row for currently enabled role or by a currently enabled role. There is one row for
each combination of type, grantor, and grantee. This view shows only each combination of type, grantor, and grantee. This view shows only
composite types (see under <xref linkend="infoschema-user-defined-types"> composite types (see under <xref linkend="infoschema-user-defined-types"/>
for why); see for why); see
<xref linkend="infoschema-usage-privileges"> for domain privileges. <xref linkend="infoschema-usage-privileges"/> for domain privileges.
</para> </para>
<table> <table>
@ -6068,7 +6068,7 @@ ORDER BY c.ordinal_position;
differentiate between these. Other user-defined types such as base differentiate between these. Other user-defined types such as base
types and enums, which are <productname>PostgreSQL</productname> types and enums, which are <productname>PostgreSQL</productname>
extensions, are not shown here. For domains, extensions, are not shown here. For domains,
see <xref linkend="infoschema-domains"> instead. see <xref linkend="infoschema-domains"/> instead.
</para> </para>
<table> <table>
@ -6522,7 +6522,7 @@ ORDER BY c.ordinal_position;
<entry><literal>sql_identifier</literal></entry> <entry><literal>sql_identifier</literal></entry>
<entry> <entry>
The <quote>specific name</quote> of the function. See <xref The <quote>specific name</quote> of the function. See <xref
linkend="infoschema-routines"> for more information. linkend="infoschema-routines"/> for more information.
</entry> </entry>
</row> </row>
</tbody> </tbody>

6
doc/src/sgml/install-windows.sgml
View File

@ -37,8 +37,8 @@
<para> <para>
Building using <productname>MinGW</productname> or Building using <productname>MinGW</productname> or
<productname>Cygwin</productname> uses the normal build system, see <productname>Cygwin</productname> uses the normal build system, see
<xref linkend="installation"> and the specific notes in <xref linkend="installation"/> and the specific notes in
<xref linkend="installation-notes-mingw"> and <xref linkend="installation-notes-cygwin">. <xref linkend="installation-notes-mingw"/> and <xref linkend="installation-notes-cygwin"/>.
To produce native 64 bit binaries in these environments, use the tools from To produce native 64 bit binaries in these environments, use the tools from
<productname>MinGW-w64</productname>. These tools can also be used to <productname>MinGW-w64</productname>. These tools can also be used to
cross-compile for 32 bit and 64 bit <productname>Windows</productname> cross-compile for 32 bit and 64 bit <productname>Windows</productname>
@ -457,7 +457,7 @@ $ENV{CONFIG}="Debug";
</screen> </screen>
For more information about the regression tests, see For more information about the regression tests, see
<xref linkend="regress">. <xref linkend="regress"/>.
</para> </para>
<para> <para>

50
doc/src/sgml/installation.sgml
View File

@ -54,7 +54,7 @@ su - postgres
In general, a modern Unix-compatible platform should be able to run In general, a modern Unix-compatible platform should be able to run
<productname>PostgreSQL</productname>. <productname>PostgreSQL</productname>.
The platforms that had received specific testing at the The platforms that had received specific testing at the
time of release are listed in <xref linkend="supported-platforms"> time of release are listed in <xref linkend="supported-platforms"/>
below. In the <filename>doc</filename> subdirectory of the distribution below. In the <filename>doc</filename> subdirectory of the distribution
there are several platform-specific <acronym>FAQ</acronym> documents you there are several platform-specific <acronym>FAQ</acronym> documents you
might wish to consult if you are having trouble. might wish to consult if you are having trouble.
@ -193,7 +193,7 @@ su - postgres
required version is <productname>Python</productname> 2.4. required version is <productname>Python</productname> 2.4.
<productname>Python 3</productname> is supported if it's <productname>Python 3</productname> is supported if it's
version 3.1 or later; but see version 3.1 or later; but see
<xref linkend="plpython-python23"> <xref linkend="plpython-python23"/>
when using Python 3. when using Python 3.
</para> </para>
@ -262,7 +262,7 @@ su - postgres
<para> <para>
To build the <productname>PostgreSQL</productname> documentation, To build the <productname>PostgreSQL</productname> documentation,
there is a separate set of requirements; see there is a separate set of requirements; see
<xref linkend="docguide-toolsets">. <xref linkend="docguide-toolsets"/>.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -358,7 +358,7 @@ su - postgres
<para> <para>
You can also get the source directly from the version control repository, see You can also get the source directly from the version control repository, see
<xref linkend="sourcerepo">. <xref linkend="sourcerepo"/>.
</para> </para>
</sect1> </sect1>
@ -835,8 +835,8 @@ su - postgres
<para> <para>
Build with <acronym>LDAP</acronym><indexterm><primary>LDAP</primary></indexterm> Build with <acronym>LDAP</acronym><indexterm><primary>LDAP</primary></indexterm>
support for authentication and connection parameter lookup (see support for authentication and connection parameter lookup (see
<phrase id="install-ldap-links"><xref linkend="libpq-ldap"> and <phrase id="install-ldap-links"><xref linkend="libpq-ldap"/> and
<xref linkend="auth-ldap"></phrase> for more information). On Unix, <xref linkend="auth-ldap"/></phrase> for more information). On Unix,
this requires the <productname>OpenLDAP</productname> package to be this requires the <productname>OpenLDAP</productname> package to be
installed. On Windows, the default <productname>WinLDAP</productname> installed. On Windows, the default <productname>WinLDAP</productname>
library is used. <filename>configure</filename> will check for the required library is used. <filename>configure</filename> will check for the required
@ -855,7 +855,7 @@ su - postgres
for <application>systemd</application><indexterm><primary>systemd</primary></indexterm> for <application>systemd</application><indexterm><primary>systemd</primary></indexterm>
service notifications. This improves integration if the server binary service notifications. This improves integration if the server binary
is started under <application>systemd</application> but has no impact is started under <application>systemd</application> but has no impact
otherwise<phrase condition="standalone-ignore">; see <xref linkend="server-start"> for more otherwise<phrase condition="standalone-ignore">; see <xref linkend="server-start"/> for more
information</phrase>. <application>libsystemd</application> and the information</phrase>. <application>libsystemd</application> and the
associated header files need to be installed to be able to use this associated header files need to be installed to be able to use this
option. option.
@ -901,7 +901,7 @@ su - postgres
<term><option>--with-uuid=<replaceable>LIBRARY</replaceable></option></term> <term><option>--with-uuid=<replaceable>LIBRARY</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Build the <xref linkend="uuid-ossp"> module Build the <xref linkend="uuid-ossp"/> module
(which provides functions to generate UUIDs), using the specified (which provides functions to generate UUIDs), using the specified
UUID library.<indexterm><primary>UUID</primary></indexterm> UUID library.<indexterm><primary>UUID</primary></indexterm>
<replaceable>LIBRARY</replaceable> must be one of: <replaceable>LIBRARY</replaceable> must be one of:
@ -968,7 +968,7 @@ su - postgres
<listitem> <listitem>
<para> <para>
Use libxslt when building the Use libxslt when building the
<xref linkend="xml2"> <xref linkend="xml2"/>
module. <application>xml2</application> relies on this library module. <application>xml2</application> relies on this library
to perform XSL transformations of XML. to perform XSL transformations of XML.
</para> </para>
@ -1084,7 +1084,7 @@ su - postgres
has no support for strong random numbers on the platform. has no support for strong random numbers on the platform.
A source of random numbers is needed for some authentication A source of random numbers is needed for some authentication
protocols, as well as some routines in the protocols, as well as some routines in the
<xref linkend="pgcrypto"> <xref linkend="pgcrypto"/>
module. <option>--disable-strong-random</option> disables functionality that module. <option>--disable-strong-random</option> disables functionality that
requires cryptographically strong random numbers, and substitutes requires cryptographically strong random numbers, and substitutes
a weak pseudo-random-number-generator for the generation of a weak pseudo-random-number-generator for the generation of
@ -1188,7 +1188,7 @@ su - postgres
code coverage testing instrumentation. When run, they code coverage testing instrumentation. When run, they
generate files in the build directory with code coverage generate files in the build directory with code coverage
metrics. metrics.
<phrase condition="standalone-ignore">See <xref linkend="regress-coverage"> <phrase condition="standalone-ignore">See <xref linkend="regress-coverage"/>
for more information.</phrase> This option is for use only with GCC for more information.</phrase> This option is for use only with GCC
and when doing development work. and when doing development work.
</para> </para>
@ -1249,7 +1249,7 @@ su - postgres
</indexterm> </indexterm>
Compiles <productname>PostgreSQL</productname> with support for the Compiles <productname>PostgreSQL</productname> with support for the
dynamic tracing tool DTrace. dynamic tracing tool DTrace.
<phrase condition="standalone-ignore">See <xref linkend="dynamic-trace"> <phrase condition="standalone-ignore">See <xref linkend="dynamic-trace"/>
for more information.</phrase> for more information.</phrase>
</para> </para>
@ -1285,7 +1285,7 @@ su - postgres
<para> <para>
Enable tests using the Perl TAP tools. This requires a Perl Enable tests using the Perl TAP tools. This requires a Perl
installation and the Perl module <literal>IPC::Run</literal>. installation and the Perl module <literal>IPC::Run</literal>.
<phrase condition="standalone-ignore">See <xref linkend="regress-tap"> for more information.</phrase> <phrase condition="standalone-ignore">See <xref linkend="regress-tap"/> for more information.</phrase>
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1442,7 +1442,7 @@ su - postgres
whether Python 2 or 3 is specified here (or otherwise whether Python 2 or 3 is specified here (or otherwise
implicitly chosen) determines which variant of the PL/Python implicitly chosen) determines which variant of the PL/Python
language becomes available. See language becomes available. See
<xref linkend="plpython-python23"> <xref linkend="plpython-python23"/>
for more information. for more information.
</para> </para>
</listitem> </listitem>
@ -1569,7 +1569,7 @@ PostgreSQL, contrib, and documentation successfully made. Ready to install.
<userinput>make check</userinput> <userinput>make check</userinput>
</screen> </screen>
(This won't work as root; do it as an unprivileged user.) (This won't work as root; do it as an unprivileged user.)
See <xref linkend="regress"> for See <xref linkend="regress"/> for
detailed information about interpreting the test results. You can detailed information about interpreting the test results. You can
repeat this test at any later time by issuing the same command. repeat this test at any later time by issuing the same command.
</para> </para>
@ -1581,7 +1581,7 @@ PostgreSQL, contrib, and documentation successfully made. Ready to install.
<note> <note>
<para> <para>
If you are upgrading an existing system be sure to read If you are upgrading an existing system be sure to read
<xref linkend="upgrading">, <xref linkend="upgrading"/>,
which has instructions about upgrading a which has instructions about upgrading a
cluster. cluster.
</para> </para>
@ -1593,7 +1593,7 @@ PostgreSQL, contrib, and documentation successfully made. Ready to install.
<userinput>make install</userinput> <userinput>make install</userinput>
</screen> </screen>
This will install files into the directories that were specified This will install files into the directories that were specified
in <xref linkend="configure">. Make sure that you have appropriate in <xref linkend="configure"/>. Make sure that you have appropriate
permissions to write into that area. Normally you need to do this permissions to write into that area. Normally you need to do this
step as root. Alternatively, you can create the target step as root. Alternatively, you can create the target
directories in advance and arrange for appropriate permissions to directories in advance and arrange for appropriate permissions to
@ -1727,7 +1727,7 @@ export LD_LIBRARY_PATH
setenv LD_LIBRARY_PATH /usr/local/pgsql/lib setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
</programlisting> </programlisting>
Replace <literal>/usr/local/pgsql/lib</literal> with whatever you set Replace <literal>/usr/local/pgsql/lib</literal> with whatever you set
<option><literal>--libdir</literal></option> to in <xref linkend="configure">. <option><literal>--libdir</literal></option> to in <xref linkend="configure"/>.
You should put these commands into a shell start-up file such as You should put these commands into a shell start-up file such as
<filename>/etc/profile</filename> or <filename>~/.bash_profile</filename>. Some <filename>/etc/profile</filename> or <filename>~/.bash_profile</filename>. Some
good information about the caveats associated with this method can good information about the caveats associated with this method can
@ -1793,7 +1793,7 @@ libpq.so.2.1: cannot open shared object file: No such file or directory
If you installed into <filename>/usr/local/pgsql</filename> or some other If you installed into <filename>/usr/local/pgsql</filename> or some other
location that is not searched for programs by default, you should location that is not searched for programs by default, you should
add <filename>/usr/local/pgsql/bin</filename> (or whatever you set add <filename>/usr/local/pgsql/bin</filename> (or whatever you set
<option><literal>--bindir</literal></option> to in <xref linkend="configure">) <option><literal>--bindir</literal></option> to in <xref linkend="configure"/>)
into your <envar>PATH</envar>. Strictly speaking, this is not into your <envar>PATH</envar>. Strictly speaking, this is not
necessary, but it will make the use of <productname>PostgreSQL</productname> necessary, but it will make the use of <productname>PostgreSQL</productname>
much more convenient. much more convenient.
@ -1873,7 +1873,7 @@ export MANPATH
Other Unix-like systems may also work but are not currently Other Unix-like systems may also work but are not currently
being tested. In most cases, all CPU architectures supported by being tested. In most cases, all CPU architectures supported by
a given operating system will work. Look in a given operating system will work. Look in
<xref linkend="installation-platform-notes"> below to see if <xref linkend="installation-platform-notes"/> below to see if
there is information there is information
specific to your operating system, particularly if using an older system. specific to your operating system, particularly if using an older system.
</para> </para>
@ -1895,8 +1895,8 @@ export MANPATH
This section documents additional platform-specific issues This section documents additional platform-specific issues
regarding the installation and setup of PostgreSQL. Be sure to regarding the installation and setup of PostgreSQL. Be sure to
read the installation instructions, and in read the installation instructions, and in
particular <xref linkend="install-requirements"> as well. Also, particular <xref linkend="install-requirements"/> as well. Also,
check <xref linkend="regress"> regarding the check <xref linkend="regress"/> regarding the
interpretation of regression test results. interpretation of regression test results.
</para> </para>
@ -2247,7 +2247,7 @@ ERROR: could not load library "/opt/dbs/pgsql/lib/plperl.so": Bad address
<para> <para>
PostgreSQL can be built using Cygwin, a Linux-like environment for PostgreSQL can be built using Cygwin, a Linux-like environment for
Windows, but that method is inferior to the native Windows build Windows, but that method is inferior to the native Windows build
<phrase condition="standalone-ignore">(see <xref linkend="install-windows">)</phrase> and <phrase condition="standalone-ignore">(see <xref linkend="install-windows"/>)</phrase> and
running a server under Cygwin is no longer recommended. running a server under Cygwin is no longer recommended.
</para> </para>
@ -2441,7 +2441,7 @@ PHSS_30849 s700_800 u2comp/be/plugin library Patch
Microsoft's <productname>Visual C++</productname> compiler suite. Microsoft's <productname>Visual C++</productname> compiler suite.
The MinGW build variant uses the normal build system described in The MinGW build variant uses the normal build system described in
this chapter; the Visual C++ build works completely differently this chapter; the Visual C++ build works completely differently
and is described in <xref linkend="install-windows">. and is described in <xref linkend="install-windows"/>.
It is a fully native build and uses no additional software like It is a fully native build and uses no additional software like
MinGW. A ready-made installer is available on the main MinGW. A ready-made installer is available on the main
PostgreSQL web site. PostgreSQL web site.
@ -2602,7 +2602,7 @@ LIBOBJS = snprintf.o
<title>Using DTrace for Tracing PostgreSQL</title> <title>Using DTrace for Tracing PostgreSQL</title>
<para> <para>
Yes, using DTrace is possible. See <xref linkend="dynamic-trace"> for Yes, using DTrace is possible. See <xref linkend="dynamic-trace"/> for
further information. further information.
</para> </para>

4
doc/src/sgml/intarray.sgml
View File

@ -29,8 +29,8 @@
<para> <para>
The functions provided by the <filename>intarray</filename> module The functions provided by the <filename>intarray</filename> module
are shown in <xref linkend="intarray-func-table">, the operators are shown in <xref linkend="intarray-func-table"/>, the operators
in <xref linkend="intarray-op-table">. in <xref linkend="intarray-op-table"/>.
</para> </para>
<table id="intarray-func-table"> <table id="intarray-func-table">

14
doc/src/sgml/intro.sgml
View File

@ -23,13 +23,13 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
<xref linkend="tutorial"> is an informal introduction for new users. <xref linkend="tutorial"/> is an informal introduction for new users.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<xref linkend="sql"> documents the <acronym>SQL</acronym> query <xref linkend="sql"/> documents the <acronym>SQL</acronym> query
language environment, including data types and functions, as well language environment, including data types and functions, as well
as user-level performance tuning. Every as user-level performance tuning. Every
<productname>PostgreSQL</productname> user should read this. <productname>PostgreSQL</productname> user should read this.
@ -38,7 +38,7 @@
<listitem> <listitem>
<para> <para>
<xref linkend="admin"> describes the installation and <xref linkend="admin"/> describes the installation and
administration of the server. Everyone who runs a administration of the server. Everyone who runs a
<productname>PostgreSQL</productname> server, be it for private <productname>PostgreSQL</productname> server, be it for private
use or for others, should read this part. use or for others, should read this part.
@ -47,7 +47,7 @@
<listitem> <listitem>
<para> <para>
<xref linkend="client-interfaces"> describes the programming <xref linkend="client-interfaces"/> describes the programming
interfaces for <productname>PostgreSQL</productname> client interfaces for <productname>PostgreSQL</productname> client
programs. programs.
</para> </para>
@ -56,7 +56,7 @@
<listitem> <listitem>
<para> <para>
<xref linkend="server-programming"> contains information for <xref linkend="server-programming"/> contains information for
advanced users about the extensibility capabilities of the advanced users about the extensibility capabilities of the
server. Topics include user-defined data types and server. Topics include user-defined data types and
functions. functions.
@ -65,7 +65,7 @@
<listitem> <listitem>
<para> <para>
<xref linkend="reference"> contains reference information about <xref linkend="reference"/> contains reference information about
SQL commands, client and server programs. This part supports SQL commands, client and server programs. This part supports
the other parts with structured information sorted by command or the other parts with structured information sorted by command or
program. program.
@ -74,7 +74,7 @@
<listitem> <listitem>
<para> <para>
<xref linkend="internals"> contains assorted information that might be of <xref linkend="internals"/> contains assorted information that might be of
use to <productname>PostgreSQL</productname> developers. use to <productname>PostgreSQL</productname> developers.
</para> </para>
</listitem> </listitem>

4
doc/src/sgml/isn.sgml
View File

@ -25,7 +25,7 @@
<title>Data Types</title> <title>Data Types</title>
<para> <para>
<xref linkend="isn-datatypes"> shows the data types provided by <xref linkend="isn-datatypes"/> shows the data types provided by
the <filename>isn</filename> module. the <filename>isn</filename> module.
</para> </para>
@ -222,7 +222,7 @@
<para> <para>
The <filename>isn</filename> module provides the standard comparison operators, The <filename>isn</filename> module provides the standard comparison operators,
plus B-tree and hash indexing support for all these data types. In plus B-tree and hash indexing support for all these data types. In
addition there are several specialized functions; shown in <xref linkend="isn-functions">. addition there are several specialized functions; shown in <xref linkend="isn-functions"/>.
In this table, In this table,
<type>isn</type> means any one of the module's data types. <type>isn</type> means any one of the module's data types.
</para> </para>

12
doc/src/sgml/json.sgml
View File

@ -18,7 +18,7 @@
the JSON data types have the advantage of enforcing that each the JSON data types have the advantage of enforcing that each
stored value is valid according to the JSON rules. There are also stored value is valid according to the JSON rules. There are also
assorted JSON-specific functions and operators available for data stored assorted JSON-specific functions and operators available for data stored
in these data types; see <xref linkend="functions-json">. in these data types; see <xref linkend="functions-json"/>.
</para> </para>
<para> <para>
@ -82,7 +82,7 @@
<note> <note>
<para> <para>
Many of the JSON processing functions described Many of the JSON processing functions described
in <xref linkend="functions-json"> will convert Unicode escapes to in <xref linkend="functions-json"/> will convert Unicode escapes to
regular characters, and will therefore throw the same types of errors regular characters, and will therefore throw the same types of errors
just described even if their input is of type <type>json</type> just described even if their input is of type <type>json</type>
not <type>jsonb</type>. The fact that the <type>json</type> input function does not <type>jsonb</type>. The fact that the <type>json</type> input function does
@ -98,7 +98,7 @@
When converting textual JSON input into <type>jsonb</type>, the primitive When converting textual JSON input into <type>jsonb</type>, the primitive
types described by <acronym>RFC</acronym> 7159 are effectively mapped onto types described by <acronym>RFC</acronym> 7159 are effectively mapped onto
native <productname>PostgreSQL</productname> types, as shown native <productname>PostgreSQL</productname> types, as shown
in <xref linkend="json-type-mapping-table">. in <xref linkend="json-type-mapping-table"/>.
Therefore, there are some minor additional constraints on what Therefore, there are some minor additional constraints on what
constitutes valid <type>jsonb</type> data that do not apply to constitutes valid <type>jsonb</type> data that do not apply to
the <type>json</type> type, nor to JSON in the abstract, corresponding the <type>json</type> type, nor to JSON in the abstract, corresponding
@ -380,7 +380,7 @@ SELECT doc-&gt;'site_name' FROM websites
<para> <para>
The various containment and existence operators, along with all other The various containment and existence operators, along with all other
JSON operators and functions are documented JSON operators and functions are documented
in <xref linkend="functions-json">. in <xref linkend="functions-json"/>.
</para> </para>
</sect2> </sect2>
@ -404,7 +404,7 @@ SELECT doc-&gt;'site_name' FROM websites
and <literal>?|</literal> operators and path/value-exists operator and <literal>?|</literal> operators and path/value-exists operator
<literal>@&gt;</literal>. <literal>@&gt;</literal>.
(For details of the semantics that these operators (For details of the semantics that these operators
implement, see <xref linkend="functions-jsonb-op-table">.) implement, see <xref linkend="functions-jsonb-op-table"/>.)
An example of creating an index with this operator class is: An example of creating an index with this operator class is:
<programlisting> <programlisting>
CREATE INDEX idxgin ON api USING GIN (jdoc); CREATE INDEX idxgin ON api USING GIN (jdoc);
@ -465,7 +465,7 @@ CREATE INDEX idxgintags ON api USING GIN ((jdoc -&gt; 'tags'));
operator <literal>?</literal> to the indexed operator <literal>?</literal> to the indexed
expression <literal>jdoc -&gt; 'tags'</literal>. expression <literal>jdoc -&gt; 'tags'</literal>.
(More information on expression indexes can be found in <xref (More information on expression indexes can be found in <xref
linkend="indexes-expressional">.) linkend="indexes-expressional"/>.)
</para> </para>
<para> <para>
Another approach to querying is to exploit containment, for example: Another approach to querying is to exploit containment, for example:

8
doc/src/sgml/keywords.sgml
View File

@ -9,10 +9,10 @@
</indexterm> </indexterm>
<para> <para>
<xref linkend="keywords-table"> lists all tokens that are key words <xref linkend="keywords-table"/> lists all tokens that are key words
in the SQL standard and in <productname>PostgreSQL</productname> in the SQL standard and in <productname>PostgreSQL</productname>
&version;. Background information can be found in <xref &version;. Background information can be found in <xref
linkend="sql-syntax-identifiers">. linkend="sql-syntax-identifiers"/>.
(For space reasons, only the latest two versions of the SQL standard, and (For space reasons, only the latest two versions of the SQL standard, and
SQL-92 for historical comparison, are included. The differences between SQL-92 for historical comparison, are included. The differences between
those and the other intermediate standard versions are small.) those and the other intermediate standard versions are small.)
@ -45,7 +45,7 @@
</para> </para>
<para> <para>
In <xref linkend="keywords-table"> in the column for In <xref linkend="keywords-table"/> in the column for
<productname>PostgreSQL</productname> we classify as <productname>PostgreSQL</productname> we classify as
<quote>non-reserved</quote> those key words that are explicitly <quote>non-reserved</quote> those key words that are explicitly
known to the parser but are allowed as column or table names. known to the parser but are allowed as column or table names.
@ -69,7 +69,7 @@
<para> <para>
It is important to understand before studying <xref It is important to understand before studying <xref
linkend="keywords-table"> that the fact that a key word is not linkend="keywords-table"/> that the fact that a key word is not
reserved in <productname>PostgreSQL</productname> does not mean that reserved in <productname>PostgreSQL</productname> does not mean that
the feature related to the word is not implemented. Conversely, the the feature related to the word is not implemented. Conversely, the
presence of a key word does not indicate the existence of a feature. presence of a key word does not indicate the existence of a feature.

156
doc/src/sgml/libpq.sgml
View File

@ -25,15 +25,15 @@
those written for C++, Perl, Python, Tcl and <application>ECPG</application>. those written for C++, Perl, Python, Tcl and <application>ECPG</application>.
So some aspects of <application>libpq</application>'s behavior will be So some aspects of <application>libpq</application>'s behavior will be
important to you if you use one of those packages. In particular, important to you if you use one of those packages. In particular,
<xref linkend="libpq-envars">, <xref linkend="libpq-envars"/>,
<xref linkend="libpq-pgpass"> and <xref linkend="libpq-pgpass"/> and
<xref linkend="libpq-ssl"> <xref linkend="libpq-ssl"/>
describe behavior that is visible to the user of any application describe behavior that is visible to the user of any application
that uses <application>libpq</application>. that uses <application>libpq</application>.
</para> </para>
<para> <para>
Some short programs are included at the end of this chapter (<xref linkend="libpq-example">) to show how Some short programs are included at the end of this chapter (<xref linkend="libpq-example"/>) to show how
to write programs that use <application>libpq</application>. There are also several to write programs that use <application>libpq</application>. There are also several
complete examples of <application>libpq</application> applications in the complete examples of <application>libpq</application> applications in the
directory <filename>src/test/examples</filename> in the source code distribution. directory <filename>src/test/examples</filename> in the source code distribution.
@ -118,7 +118,7 @@ PGconn *PQconnectdbParams(const char * const *keywords,
<para> <para>
The currently recognized parameter key words are listed in The currently recognized parameter key words are listed in
<xref linkend="libpq-paramkeywords">. <xref linkend="libpq-paramkeywords"/>.
</para> </para>
<para> <para>
@ -128,7 +128,7 @@ PGconn *PQconnectdbParams(const char * const *keywords,
<parameter>dbname</parameter> is expanded this way, any subsequent <parameter>dbname</parameter> is expanded this way, any subsequent
<parameter>dbname</parameter> value is processed as plain database name. More <parameter>dbname</parameter> value is processed as plain database name. More
details on the possible connection string formats appear in details on the possible connection string formats appear in
<xref linkend="libpq-connstring">. <xref linkend="libpq-connstring"/>.
</para> </para>
<para> <para>
@ -140,7 +140,7 @@ PGconn *PQconnectdbParams(const char * const *keywords,
<para> <para>
If any parameter is <symbol>NULL</symbol> or an empty string, the corresponding If any parameter is <symbol>NULL</symbol> or an empty string, the corresponding
environment variable (see <xref linkend="libpq-envars">) is checked. environment variable (see <xref linkend="libpq-envars"/>) is checked.
If the environment variable is not set either, then the indicated If the environment variable is not set either, then the indicated
built-in defaults are used. built-in defaults are used.
</para> </para>
@ -176,7 +176,7 @@ PGconn *PQconnectdb(const char *conninfo);
The passed string can be empty to use all default parameters, or it can The passed string can be empty to use all default parameters, or it can
contain one or more parameter settings separated by whitespace, contain one or more parameter settings separated by whitespace,
or it can contain a <acronym>URI</acronym>. or it can contain a <acronym>URI</acronym>.
See <xref linkend="libpq-connstring"> for details. See <xref linkend="libpq-connstring"/> for details.
</para> </para>
@ -289,7 +289,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
<para> <para>
The <literal>hostaddr</literal> and <literal>host</literal> parameters are used appropriately to ensure that The <literal>hostaddr</literal> and <literal>host</literal> parameters are used appropriately to ensure that
name and reverse name queries are not made. See the documentation of name and reverse name queries are not made. See the documentation of
these parameters in <xref linkend="libpq-paramkeywords"> for details. these parameters in <xref linkend="libpq-paramkeywords"/> for details.
</para> </para>
</listitem> </listitem>
@ -802,7 +802,7 @@ host=localhost port=5432 dbname=mydb connect_timeout=10
<para> <para>
The recognized parameter key words are listed in <xref The recognized parameter key words are listed in <xref
linkend="libpq-paramkeywords">. linkend="libpq-paramkeywords"/>.
</para> </para>
</sect3> </sect3>
@ -847,7 +847,7 @@ postgresql:///mydb?host=localhost&amp;port=5433
<para> <para>
Any connection parameters not corresponding to key words listed in <xref Any connection parameters not corresponding to key words listed in <xref
linkend="libpq-paramkeywords"> are ignored and a warning message about them linkend="libpq-paramkeywords"/> are ignored and a warning message about them
is sent to <filename>stderr</filename>. is sent to <filename>stderr</filename>.
</para> </para>
@ -867,7 +867,7 @@ postgresql://[2001:db8::1234]/database
<para> <para>
The host component is interpreted as described for the parameter <xref The host component is interpreted as described for the parameter <xref
linkend="libpq-connect-host">. In particular, a Unix-domain socket linkend="libpq-connect-host"/>. In particular, a Unix-domain socket
connection is chosen if the host part is either empty or starts with a connection is chosen if the host part is either empty or starts with a
slash, otherwise a TCP/IP connection is initiated. Note, however, that the slash, otherwise a TCP/IP connection is initiated. Note, however, that the
slash is a reserved character in the hierarchical part of the URI. So, to slash is a reserved character in the hierarchical part of the URI. So, to
@ -954,7 +954,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
<para> <para>
A comma-separated list of host names is also accepted, in which case A comma-separated list of host names is also accepted, in which case
each host name in the list is tried in order. See each host name in the list is tried in order. See
<xref linkend="libpq-multiple-hosts"> for details. <xref linkend="libpq-multiple-hosts"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1006,13 +1006,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
is not the name of the server at network address <literal>hostaddr</literal>. is not the name of the server at network address <literal>hostaddr</literal>.
Also, note that <literal>host</literal> rather than <literal>hostaddr</literal> Also, note that <literal>host</literal> rather than <literal>hostaddr</literal>
is used to identify the connection in a password file (see is used to identify the connection in a password file (see
<xref linkend="libpq-pgpass">). <xref linkend="libpq-pgpass"/>).
</para> </para>
<para> <para>
A comma-separated list of <literal>hostaddrs</literal> is also accepted, in A comma-separated list of <literal>hostaddrs</literal> is also accepted, in
which case each host in the list is tried in order. See which case each host in the list is tried in order. See
<xref linkend="libpq-multiple-hosts"> for details. <xref linkend="libpq-multiple-hosts"/> for details.
</para> </para>
<para> <para>
Without either a host name or host address, Without either a host name or host address,
@ -1044,7 +1044,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
<para> <para>
The database name. Defaults to be the same as the user name. The database name. Defaults to be the same as the user name.
In certain contexts, the value is checked for extended In certain contexts, the value is checked for extended
formats; see <xref linkend="libpq-connstring"> for more details on formats; see <xref linkend="libpq-connstring"/> for more details on
those. those.
</para> </para>
</listitem> </listitem>
@ -1075,7 +1075,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
<listitem> <listitem>
<para> <para>
Specifies the name of the file used to store passwords Specifies the name of the file used to store passwords
(see <xref linkend="libpq-pgpass">). (see <xref linkend="libpq-pgpass"/>).
Defaults to <filename>~/.pgpass</filename>, or Defaults to <filename>~/.pgpass</filename>, or
<filename>%APPDATA%\postgresql\pgpass.conf</filename> on Microsoft Windows. <filename>%APPDATA%\postgresql\pgpass.conf</filename> on Microsoft Windows.
(No error is reported if this file does not exist.) (No error is reported if this file does not exist.)
@ -1125,7 +1125,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
separate command-line arguments, unless escaped with a backslash separate command-line arguments, unless escaped with a backslash
(<literal>\</literal>); write <literal>\\</literal> to represent a literal (<literal>\</literal>); write <literal>\\</literal> to represent a literal
backslash. For a detailed discussion of the available backslash. For a detailed discussion of the available
options, consult <xref linkend="runtime-config">. options, consult <xref linkend="runtime-config"/>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1134,7 +1134,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
<term><literal>application_name</literal></term> <term><literal>application_name</literal></term>
<listitem> <listitem>
<para> <para>
Specifies a value for the <xref linkend="guc-application-name"> Specifies a value for the <xref linkend="guc-application-name"/>
configuration parameter. configuration parameter.
</para> </para>
</listitem> </listitem>
@ -1145,7 +1145,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
<listitem> <listitem>
<para> <para>
Specifies a fallback value for the <xref Specifies a fallback value for the <xref
linkend="guc-application-name"> configuration parameter. linkend="guc-application-name"/> configuration parameter.
This value will be used if no value has been given for This value will be used if no value has been given for
<literal>application_name</literal> via a connection parameter or the <literal>application_name</literal> via a connection parameter or the
<envar>PGAPPNAME</envar> environment variable. Specifying <envar>PGAPPNAME</envar> environment variable. Specifying
@ -1295,7 +1295,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
</varlistentry> </varlistentry>
</variablelist> </variablelist>
See <xref linkend="libpq-ssl"> for a detailed description of how See <xref linkend="libpq-ssl"/> for a detailed description of how
these options work. these options work.
</para> </para>
@ -1430,7 +1430,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
to ensure that you are connected to a server run by a trusted user.) to ensure that you are connected to a server run by a trusted user.)
This option is only supported on platforms for which the This option is only supported on platforms for which the
<literal>peer</literal> authentication method is implemented; see <literal>peer</literal> authentication method is implemented; see
<xref linkend="auth-peer">. <xref linkend="auth-peer"/>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1442,7 +1442,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
Kerberos service name to use when authenticating with GSSAPI. Kerberos service name to use when authenticating with GSSAPI.
This must match the service name specified in the server This must match the service name specified in the server
configuration for Kerberos authentication to succeed. (See also configuration for Kerberos authentication to succeed. (See also
<xref linkend="gssapi-auth">.) <xref linkend="gssapi-auth"/>.)
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1465,7 +1465,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
Service name to use for additional parameters. It specifies a service Service name to use for additional parameters. It specifies a service
name in <filename>pg_service.conf</filename> that holds additional connection parameters. name in <filename>pg_service.conf</filename> that holds additional connection parameters.
This allows applications to specify only a service name so connection parameters This allows applications to specify only a service name so connection parameters
can be centrally maintained. See <xref linkend="libpq-pgservice">. can be centrally maintained. See <xref linkend="libpq-pgservice"/>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -2225,7 +2225,7 @@ PGresult *PQexec(PGconn *conn, const char *command);
<function>PQexec</function> call are processed in a single transaction, unless <function>PQexec</function> call are processed in a single transaction, unless
there are explicit <command>BEGIN</command>/<command>COMMIT</command> there are explicit <command>BEGIN</command>/<command>COMMIT</command>
commands included in the query string to divide it into multiple commands included in the query string to divide it into multiple
transactions. (See <xref linkend="protocol-flow-multi-statement"> transactions. (See <xref linkend="protocol-flow-multi-statement"/>
for more details about how the server handles multi-query strings.) for more details about how the server handles multi-query strings.)
Note however that the returned Note however that the returned
<structname>PGresult</structname> structure describes only the result <structname>PGresult</structname> structure describes only the result
@ -2447,7 +2447,7 @@ PGresult *PQprepare(PGconn *conn,
<function>PQprepare</function> creates a prepared statement for later <function>PQprepare</function> creates a prepared statement for later
execution with <function>PQexecPrepared</function>. This feature allows execution with <function>PQexecPrepared</function>. This feature allows
commands to be executed repeatedly without being parsed and commands to be executed repeatedly without being parsed and
planned each time; see <xref linkend="sql-prepare"> for details. planned each time; see <xref linkend="sql-prepare"/> for details.
<function>PQprepare</function> is supported only in protocol 3.0 and later <function>PQprepare</function> is supported only in protocol 3.0 and later
connections; it will fail when using protocol 2.0. connections; it will fail when using protocol 2.0.
</para> </para>
@ -2489,10 +2489,10 @@ PGresult *PQprepare(PGconn *conn,
</variablelist> </variablelist>
Prepared statements for use with <function>PQexecPrepared</function> can also Prepared statements for use with <function>PQexecPrepared</function> can also
be created by executing SQL <xref linkend="sql-prepare"> be created by executing SQL <xref linkend="sql-prepare"/>
statements. Also, although there is no <application>libpq</application> statements. Also, although there is no <application>libpq</application>
function for deleting a prepared statement, the SQL <xref function for deleting a prepared statement, the SQL <xref
linkend="sql-deallocate"> statement linkend="sql-deallocate"/> statement
can be used for that purpose. can be used for that purpose.
</para> </para>
@ -2746,7 +2746,7 @@ ExecStatusType PQresultStatus(const PGresult *res);
The <structname>PGresult</structname> contains a single result tuple The <structname>PGresult</structname> contains a single result tuple
from the current command. This status occurs only when from the current command. This status occurs only when
single-row mode has been selected for the query single-row mode has been selected for the query
(see <xref linkend="libpq-single-row-mode">). (see <xref linkend="libpq-single-row-mode"/>).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -2770,7 +2770,7 @@ ExecStatusType PQresultStatus(const PGresult *res);
never be returned directly by <function>PQexec</function> or other never be returned directly by <function>PQexec</function> or other
query execution functions; results of this kind are instead passed query execution functions; results of this kind are instead passed
to the notice processor (see <xref to the notice processor (see <xref
linkend="libpq-notice-processing">). linkend="libpq-notice-processing"/>).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -2941,7 +2941,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode);
front-end applications to perform specific operations (such front-end applications to perform specific operations (such
as error handling) in response to a particular database error. as error handling) in response to a particular database error.
For a list of the possible SQLSTATE codes, see <xref For a list of the possible SQLSTATE codes, see <xref
linkend="errcodes-appendix">. This field is not localizable, linkend="errcodes-appendix"/>. This field is not localizable,
and is always present. and is always present.
</para> </para>
</listitem> </listitem>
@ -3118,7 +3118,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode);
<para> <para>
The fields for schema name, table name, column name, data type name, The fields for schema name, table name, column name, data type name,
and constraint name are supplied only for a limited number of error and constraint name are supplied only for a limited number of error
types; see <xref linkend="errcodes-appendix">. Do not assume that types; see <xref linkend="errcodes-appendix"/>. Do not assume that
the presence of any of these fields guarantees the presence of the presence of any of these fields guarantees the presence of
another field. Core error sources observe the interrelationships another field. Core error sources observe the interrelationships
noted above, but user-defined functions may use these fields in other noted above, but user-defined functions may use these fields in other
@ -4075,7 +4075,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn,
<type>bytea</type> literal in an <acronym>SQL</acronym> statement. <type>bytea</type> literal in an <acronym>SQL</acronym> statement.
<function>PQescapeByteaConn</function> escapes bytes using <function>PQescapeByteaConn</function> escapes bytes using
either hex encoding or backslash escaping. See <xref either hex encoding or backslash escaping. See <xref
linkend="datatype-binary"> for more information. linkend="datatype-binary"/> for more information.
</para> </para>
<para> <para>
@ -4508,7 +4508,7 @@ PGresult *PQgetResult(PGconn *conn);
Another frequently-desired feature that can be obtained with Another frequently-desired feature that can be obtained with
<function>PQsendQuery</function> and <function>PQgetResult</function> <function>PQsendQuery</function> and <function>PQgetResult</function>
is retrieving large query results a row at a time. This is discussed is retrieving large query results a row at a time. This is discussed
in <xref linkend="libpq-single-row-mode">. in <xref linkend="libpq-single-row-mode"/>.
</para> </para>
<para> <para>
@ -4600,14 +4600,14 @@ int PQisBusy(PGconn *conn);
<function>PQgetResult</function> if <function>PQisBusy</function> <function>PQgetResult</function> if <function>PQisBusy</function>
returns false (0). It can also call <function>PQnotifies</function> returns false (0). It can also call <function>PQnotifies</function>
to detect <command>NOTIFY</command> messages (see <xref to detect <command>NOTIFY</command> messages (see <xref
linkend="libpq-notify">). linkend="libpq-notify"/>).
</para> </para>
<para> <para>
A client that uses A client that uses
<function>PQsendQuery</function>/<function>PQgetResult</function> <function>PQsendQuery</function>/<function>PQgetResult</function>
can also attempt to cancel a command that is still being processed can also attempt to cancel a command that is still being processed
by the server; see <xref linkend="libpq-cancel">. But regardless of by the server; see <xref linkend="libpq-cancel"/>. But regardless of
the return value of <function>PQcancel</function>, the application the return value of <function>PQcancel</function>, the application
must continue with the normal result-reading sequence using must continue with the normal result-reading sequence using
<function>PQgetResult</function>. A successful cancellation will <function>PQgetResult</function>. A successful cancellation will
@ -4753,7 +4753,7 @@ int PQflush(PGconn *conn);
(or a sibling function). This mode selection is effective only for the (or a sibling function). This mode selection is effective only for the
currently executing query. Then call <function>PQgetResult</function> currently executing query. Then call <function>PQgetResult</function>
repeatedly, until it returns null, as documented in <xref repeatedly, until it returns null, as documented in <xref
linkend="libpq-async">. If the query returns any rows, they are returned linkend="libpq-async"/>. If the query returns any rows, they are returned
as individual <structname>PGresult</structname> objects, which look like as individual <structname>PGresult</structname> objects, which look like
normal query results except for having status code normal query results except for having status code
<literal>PGRES_SINGLE_TUPLE</literal> instead of <literal>PGRES_SINGLE_TUPLE</literal> instead of
@ -5119,7 +5119,7 @@ typedef struct pgNotify
</para> </para>
<para> <para>
<xref linkend="libpq-example-2"> gives a sample program that illustrates <xref linkend="libpq-example-2"/> gives a sample program that illustrates
the use of asynchronous notification. the use of asynchronous notification.
</para> </para>
@ -5242,7 +5242,7 @@ typedef struct pgNotify
0 indicates the overall copy format is textual (rows separated by 0 indicates the overall copy format is textual (rows separated by
newlines, columns separated by separator characters, etc). 1 newlines, columns separated by separator characters, etc). 1
indicates the overall copy format is binary. See <xref indicates the overall copy format is binary. See <xref
linkend="sql-copy"> for more information. linkend="sql-copy"/> for more information.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -5322,7 +5322,7 @@ int PQputCopyData(PGconn *conn,
into buffer loads of any convenient size. Buffer-load boundaries into buffer loads of any convenient size. Buffer-load boundaries
have no semantic significance when sending. The contents of the have no semantic significance when sending. The contents of the
data stream must match the data format expected by the data stream must match the data format expected by the
<command>COPY</command> command; see <xref linkend="sql-copy"> for details. <command>COPY</command> command; see <xref linkend="sql-copy"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -5982,7 +5982,7 @@ char *PQencryptPasswordConn(PGconn *conn, const char *passwd, const char *user,
version 10, and will not work correctly with older server versions. If version 10, and will not work correctly with older server versions. If
<parameter>algorithm</parameter> is <symbol>NULL</symbol>, this function will query <parameter>algorithm</parameter> is <symbol>NULL</symbol>, this function will query
the server for the current value of the the server for the current value of the
<xref linkend="guc-password-encryption"> setting. That can block, and <xref linkend="guc-password-encryption"/> setting. That can block, and
will fail if the current transaction is aborted, or if the connection will fail if the current transaction is aborted, or if the connection
is busy executing another query. If you wish to use the default is busy executing another query. If you wish to use the default
algorithm for the server but want to avoid blocking, query algorithm for the server but want to avoid blocking, query
@ -6072,7 +6072,7 @@ PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
<listitem> <listitem>
<para> <para>
Fires a <literal>PGEVT_RESULTCREATE</literal> event (see <xref Fires a <literal>PGEVT_RESULTCREATE</literal> event (see <xref
linkend="libpq-events">) for each event procedure registered in the linkend="libpq-events"/>) for each event procedure registered in the
<structname>PGresult</structname> object. Returns non-zero for success, <structname>PGresult</structname> object. Returns non-zero for success,
zero if any event procedure fails. zero if any event procedure fails.
@ -7004,7 +7004,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGHOST</envar></primary> <primary><envar>PGHOST</envar></primary>
</indexterm> </indexterm>
<envar>PGHOST</envar> behaves the same as the <xref <envar>PGHOST</envar> behaves the same as the <xref
linkend="libpq-connect-host"> connection parameter. linkend="libpq-connect-host"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7014,7 +7014,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGHOSTADDR</envar></primary> <primary><envar>PGHOSTADDR</envar></primary>
</indexterm> </indexterm>
<envar>PGHOSTADDR</envar> behaves the same as the <xref <envar>PGHOSTADDR</envar> behaves the same as the <xref
linkend="libpq-connect-hostaddr"> connection parameter. linkend="libpq-connect-hostaddr"/> connection parameter.
This can be set instead of or in addition to <envar>PGHOST</envar> This can be set instead of or in addition to <envar>PGHOST</envar>
to avoid DNS lookup overhead. to avoid DNS lookup overhead.
</para> </para>
@ -7026,7 +7026,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGPORT</envar></primary> <primary><envar>PGPORT</envar></primary>
</indexterm> </indexterm>
<envar>PGPORT</envar> behaves the same as the <xref <envar>PGPORT</envar> behaves the same as the <xref
linkend="libpq-connect-port"> connection parameter. linkend="libpq-connect-port"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7036,7 +7036,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGDATABASE</envar></primary> <primary><envar>PGDATABASE</envar></primary>
</indexterm> </indexterm>
<envar>PGDATABASE</envar> behaves the same as the <xref <envar>PGDATABASE</envar> behaves the same as the <xref
linkend="libpq-connect-dbname"> connection parameter. linkend="libpq-connect-dbname"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7046,7 +7046,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGUSER</envar></primary> <primary><envar>PGUSER</envar></primary>
</indexterm> </indexterm>
<envar>PGUSER</envar> behaves the same as the <xref <envar>PGUSER</envar> behaves the same as the <xref
linkend="libpq-connect-user"> connection parameter. linkend="libpq-connect-user"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7056,12 +7056,12 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGPASSWORD</envar></primary> <primary><envar>PGPASSWORD</envar></primary>
</indexterm> </indexterm>
<envar>PGPASSWORD</envar> behaves the same as the <xref <envar>PGPASSWORD</envar> behaves the same as the <xref
linkend="libpq-connect-password"> connection parameter. linkend="libpq-connect-password"/> connection parameter.
Use of this environment variable Use of this environment variable
is not recommended for security reasons, as some operating systems is not recommended for security reasons, as some operating systems
allow non-root users to see process environment variables via allow non-root users to see process environment variables via
<application>ps</application>; instead consider using a password file <application>ps</application>; instead consider using a password file
(see <xref linkend="libpq-pgpass">). (see <xref linkend="libpq-pgpass"/>).
</para> </para>
</listitem> </listitem>
@ -7071,7 +7071,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGPASSFILE</envar></primary> <primary><envar>PGPASSFILE</envar></primary>
</indexterm> </indexterm>
<envar>PGPASSFILE</envar> behaves the same as the <xref <envar>PGPASSFILE</envar> behaves the same as the <xref
linkend="libpq-connect-passfile"> connection parameter. linkend="libpq-connect-passfile"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7081,7 +7081,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGSERVICE</envar></primary> <primary><envar>PGSERVICE</envar></primary>
</indexterm> </indexterm>
<envar>PGSERVICE</envar> behaves the same as the <xref <envar>PGSERVICE</envar> behaves the same as the <xref
linkend="libpq-connect-service"> connection parameter. linkend="libpq-connect-service"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7093,7 +7093,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<envar>PGSERVICEFILE</envar> specifies the name of the per-user <envar>PGSERVICEFILE</envar> specifies the name of the per-user
connection service file. If not set, it defaults connection service file. If not set, it defaults
to <filename>~/.pg_service.conf</filename> to <filename>~/.pg_service.conf</filename>
(see <xref linkend="libpq-pgservice">). (see <xref linkend="libpq-pgservice"/>).
</para> </para>
</listitem> </listitem>
@ -7103,7 +7103,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGOPTIONS</envar></primary> <primary><envar>PGOPTIONS</envar></primary>
</indexterm> </indexterm>
<envar>PGOPTIONS</envar> behaves the same as the <xref <envar>PGOPTIONS</envar> behaves the same as the <xref
linkend="libpq-connect-options"> connection parameter. linkend="libpq-connect-options"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7113,7 +7113,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGAPPNAME</envar></primary> <primary><envar>PGAPPNAME</envar></primary>
</indexterm> </indexterm>
<envar>PGAPPNAME</envar> behaves the same as the <xref <envar>PGAPPNAME</envar> behaves the same as the <xref
linkend="libpq-connect-application-name"> connection parameter. linkend="libpq-connect-application-name"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7123,7 +7123,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGSSLMODE</envar></primary> <primary><envar>PGSSLMODE</envar></primary>
</indexterm> </indexterm>
<envar>PGSSLMODE</envar> behaves the same as the <xref <envar>PGSSLMODE</envar> behaves the same as the <xref
linkend="libpq-connect-sslmode"> connection parameter. linkend="libpq-connect-sslmode"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7133,7 +7133,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGREQUIRESSL</envar></primary> <primary><envar>PGREQUIRESSL</envar></primary>
</indexterm> </indexterm>
<envar>PGREQUIRESSL</envar> behaves the same as the <xref <envar>PGREQUIRESSL</envar> behaves the same as the <xref
linkend="libpq-connect-requiressl"> connection parameter. linkend="libpq-connect-requiressl"/> connection parameter.
This environment variable is deprecated in favor of the This environment variable is deprecated in favor of the
<envar>PGSSLMODE</envar> variable; setting both variables suppresses the <envar>PGSSLMODE</envar> variable; setting both variables suppresses the
effect of this one. effect of this one.
@ -7146,7 +7146,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGSSLCOMPRESSION</envar></primary> <primary><envar>PGSSLCOMPRESSION</envar></primary>
</indexterm> </indexterm>
<envar>PGSSLCOMPRESSION</envar> behaves the same as the <xref <envar>PGSSLCOMPRESSION</envar> behaves the same as the <xref
linkend="libpq-connect-sslcompression"> connection parameter. linkend="libpq-connect-sslcompression"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7156,7 +7156,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGSSLCERT</envar></primary> <primary><envar>PGSSLCERT</envar></primary>
</indexterm> </indexterm>
<envar>PGSSLCERT</envar> behaves the same as the <xref <envar>PGSSLCERT</envar> behaves the same as the <xref
linkend="libpq-connect-sslcert"> connection parameter. linkend="libpq-connect-sslcert"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7166,7 +7166,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGSSLKEY</envar></primary> <primary><envar>PGSSLKEY</envar></primary>
</indexterm> </indexterm>
<envar>PGSSLKEY</envar> behaves the same as the <xref <envar>PGSSLKEY</envar> behaves the same as the <xref
linkend="libpq-connect-sslkey"> connection parameter. linkend="libpq-connect-sslkey"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7176,7 +7176,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGSSLROOTCERT</envar></primary> <primary><envar>PGSSLROOTCERT</envar></primary>
</indexterm> </indexterm>
<envar>PGSSLROOTCERT</envar> behaves the same as the <xref <envar>PGSSLROOTCERT</envar> behaves the same as the <xref
linkend="libpq-connect-sslrootcert"> connection parameter. linkend="libpq-connect-sslrootcert"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7186,7 +7186,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGSSLCRL</envar></primary> <primary><envar>PGSSLCRL</envar></primary>
</indexterm> </indexterm>
<envar>PGSSLCRL</envar> behaves the same as the <xref <envar>PGSSLCRL</envar> behaves the same as the <xref
linkend="libpq-connect-sslcrl"> connection parameter. linkend="libpq-connect-sslcrl"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7196,7 +7196,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGREQUIREPEER</envar></primary> <primary><envar>PGREQUIREPEER</envar></primary>
</indexterm> </indexterm>
<envar>PGREQUIREPEER</envar> behaves the same as the <xref <envar>PGREQUIREPEER</envar> behaves the same as the <xref
linkend="libpq-connect-requirepeer"> connection parameter. linkend="libpq-connect-requirepeer"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7206,7 +7206,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGKRBSRVNAME</envar></primary> <primary><envar>PGKRBSRVNAME</envar></primary>
</indexterm> </indexterm>
<envar>PGKRBSRVNAME</envar> behaves the same as the <xref <envar>PGKRBSRVNAME</envar> behaves the same as the <xref
linkend="libpq-connect-krbsrvname"> connection parameter. linkend="libpq-connect-krbsrvname"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7216,7 +7216,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGGSSLIB</envar></primary> <primary><envar>PGGSSLIB</envar></primary>
</indexterm> </indexterm>
<envar>PGGSSLIB</envar> behaves the same as the <xref <envar>PGGSSLIB</envar> behaves the same as the <xref
linkend="libpq-connect-gsslib"> connection parameter. linkend="libpq-connect-gsslib"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7226,7 +7226,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGCONNECT_TIMEOUT</envar></primary> <primary><envar>PGCONNECT_TIMEOUT</envar></primary>
</indexterm> </indexterm>
<envar>PGCONNECT_TIMEOUT</envar> behaves the same as the <xref <envar>PGCONNECT_TIMEOUT</envar> behaves the same as the <xref
linkend="libpq-connect-connect-timeout"> connection parameter. linkend="libpq-connect-connect-timeout"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7236,7 +7236,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGCLIENTENCODING</envar></primary> <primary><envar>PGCLIENTENCODING</envar></primary>
</indexterm> </indexterm>
<envar>PGCLIENTENCODING</envar> behaves the same as the <xref <envar>PGCLIENTENCODING</envar> behaves the same as the <xref
linkend="libpq-connect-client-encoding"> connection parameter. linkend="libpq-connect-client-encoding"/> connection parameter.
</para> </para>
</listitem> </listitem>
@ -7246,7 +7246,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<primary><envar>PGTARGETSESSIONATTRS</envar></primary> <primary><envar>PGTARGETSESSIONATTRS</envar></primary>
</indexterm> </indexterm>
<envar>PGTARGETSESSIONATTRS</envar> behaves the same as the <xref <envar>PGTARGETSESSIONATTRS</envar> behaves the same as the <xref
linkend="libpq-connect-target-session-attrs"> connection parameter. linkend="libpq-connect-target-session-attrs"/> connection parameter.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -7255,8 +7255,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<para> <para>
The following environment variables can be used to specify default The following environment variables can be used to specify default
behavior for each <productname>PostgreSQL</productname> session. (See behavior for each <productname>PostgreSQL</productname> session. (See
also the <xref linkend="sql-alterrole"> also the <xref linkend="sql-alterrole"/>
and <xref linkend="sql-alterdatabase"> and <xref linkend="sql-alterdatabase"/>
commands for ways to set default behavior on a per-user or per-database commands for ways to set default behavior on a per-user or per-database
basis.) basis.)
@ -7293,7 +7293,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
</listitem> </listitem>
</itemizedlist> </itemizedlist>
Refer to the <acronym>SQL</acronym> command <xref linkend="sql-set"> Refer to the <acronym>SQL</acronym> command <xref linkend="sql-set"/>
for information on correct values for these for information on correct values for these
environment variables. environment variables.
</para> </para>
@ -7348,7 +7348,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<filename>%APPDATA%</filename> refers to the Application Data subdirectory in <filename>%APPDATA%</filename> refers to the Application Data subdirectory in
the user's profile). the user's profile).
Alternatively, a password file can be specified Alternatively, a password file can be specified
using the connection parameter <xref linkend="libpq-connect-passfile"> using the connection parameter <xref linkend="libpq-connect-passfile"/>
or the environment variable <envar>PGPASSFILE</envar>. or the environment variable <envar>PGPASSFILE</envar>.
</para> </para>
@ -7422,7 +7422,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
<para> <para>
The file uses an <quote>INI file</quote> format where the section The file uses an <quote>INI file</quote> format where the section
name is the service name and the parameters are connection name is the service name and the parameters are connection
parameters; see <xref linkend="libpq-paramkeywords"> for a list. For parameters; see <xref linkend="libpq-paramkeywords"/> for a list. For
example: example:
<programlisting> <programlisting>
# comment # comment
@ -7456,7 +7456,7 @@ user=admin
<para> <para>
LDAP connection parameter lookup uses the connection service file LDAP connection parameter lookup uses the connection service file
<filename>pg_service.conf</filename> (see <xref <filename>pg_service.conf</filename> (see <xref
linkend="libpq-pgservice">). A line in a linkend="libpq-pgservice"/>). A line in a
<filename>pg_service.conf</filename> stanza that starts with <filename>pg_service.conf</filename> stanza that starts with
<literal>ldap://</literal> will be recognized as an LDAP URL and an <literal>ldap://</literal> will be recognized as an LDAP URL and an
LDAP query will be performed. The result must be a list of LDAP query will be performed. The result must be a list of
@ -7528,7 +7528,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
<para> <para>
<productname>PostgreSQL</productname> has native support for using <acronym>SSL</acronym> <productname>PostgreSQL</productname> has native support for using <acronym>SSL</acronym>
connections to encrypt client/server communications for increased connections to encrypt client/server communications for increased
security. See <xref linkend="ssl-tcp"> for details about the server-side security. See <xref linkend="ssl-tcp"/> for details about the server-side
<acronym>SSL</acronym> functionality. <acronym>SSL</acronym> functionality.
</para> </para>
@ -7643,7 +7643,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
file, then its parent authority's certificate, and so on up to a certificate file, then its parent authority's certificate, and so on up to a certificate
authority, <quote>root</quote> or <quote>intermediate</quote>, that is trusted by authority, <quote>root</quote> or <quote>intermediate</quote>, that is trusted by
the server, i.e. signed by a certificate in the server's root CA file the server, i.e. signed by a certificate in the server's root CA file
(<xref linkend="guc-ssl-ca-file">). (<xref linkend="guc-ssl-ca-file"/>).
</para> </para>
<para> <para>
@ -7728,7 +7728,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
<para> <para>
All <acronym>SSL</acronym> options carry overhead in the form of encryption and All <acronym>SSL</acronym> options carry overhead in the form of encryption and
key-exchange, so there is a trade-off that has to be made between performance key-exchange, so there is a trade-off that has to be made between performance
and security. <xref linkend="libpq-ssl-sslmode-statements"> and security. <xref linkend="libpq-ssl-sslmode-statements"/>
illustrates the risks the different <literal>sslmode</literal> values illustrates the risks the different <literal>sslmode</literal> values
protect against, and what statement they make about security and overhead. protect against, and what statement they make about security and overhead.
</para> </para>
@ -7828,7 +7828,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
<title>SSL Client File Usage</title> <title>SSL Client File Usage</title>
<para> <para>
<xref linkend="libpq-ssl-file-usage"> summarizes the files that are <xref linkend="libpq-ssl-file-usage"/> summarizes the files that are
relevant to the SSL setup on the client. relevant to the SSL setup on the client.
</para> </para>
@ -8027,7 +8027,7 @@ int PQisthreadsafe();
<structname>PGresult</structname> objects are normally read-only after creation, <structname>PGresult</structname> objects are normally read-only after creation,
and so can be passed around freely between threads. However, if you use and so can be passed around freely between threads. However, if you use
any of the <structname>PGresult</structname>-modifying functions described in any of the <structname>PGresult</structname>-modifying functions described in
<xref linkend="libpq-misc"> or <xref linkend="libpq-events">, it's up <xref linkend="libpq-misc"/> or <xref linkend="libpq-events"/>, it's up
to you to avoid concurrent operations on the same <structname>PGresult</structname>, to you to avoid concurrent operations on the same <structname>PGresult</structname>,
too. too.
</para> </para>

2
doc/src/sgml/lo.sgml
View File

@ -102,7 +102,7 @@ CREATE TRIGGER t_raster BEFORE UPDATE OR DELETE ON image
<para> <para>
If you already have, or suspect you have, orphaned large objects, see the If you already have, or suspect you have, orphaned large objects, see the
<xref linkend="vacuumlo"> module to help <xref linkend="vacuumlo"/> module to help
you clean them up. It's a good idea to run <application>vacuumlo</application> you clean them up. It's a good idea to run <application>vacuumlo</application>
occasionally as a back-stop to the <function>lo_manage</function> trigger. occasionally as a back-stop to the <function>lo_manage</function> trigger.
</para> </para>

14
doc/src/sgml/lobj.sgml
View File

@ -83,8 +83,8 @@
<para> <para>
As of <productname>PostgreSQL</productname> 9.0, large objects have an owner As of <productname>PostgreSQL</productname> 9.0, large objects have an owner
and a set of access permissions, which can be managed using and a set of access permissions, which can be managed using
<xref linkend="sql-grant"> and <xref linkend="sql-grant"/> and
<xref linkend="sql-revoke">. <xref linkend="sql-revoke"/>.
<literal>SELECT</literal> privileges are required to read a large <literal>SELECT</literal> privileges are required to read a large
object, and object, and
<literal>UPDATE</literal> privileges are required to write or <literal>UPDATE</literal> privileges are required to write or
@ -92,7 +92,7 @@
Only the large object's owner (or a database superuser) can delete, Only the large object's owner (or a database superuser) can delete,
comment on, or change the owner of a large object. comment on, or change the owner of a large object.
To adjust this behavior for compatibility with prior releases, see the To adjust this behavior for compatibility with prior releases, see the
<xref linkend="guc-lo-compat-privileges"> run-time parameter. <xref linkend="guc-lo-compat-privileges"/> run-time parameter.
</para> </para>
</sect1> </sect1>
@ -301,7 +301,7 @@ int lo_open(PGconn *conn, Oid lobjId, int mode);
checks were instead performed at the first actual read or write call checks were instead performed at the first actual read or write call
using the descriptor.) using the descriptor.)
These privilege checks can be disabled with the These privilege checks can be disabled with the
<xref linkend="guc-lo-compat-privileges"> run-time parameter. <xref linkend="guc-lo-compat-privileges"/> run-time parameter.
</para> </para>
<para> <para>
@ -539,7 +539,7 @@ int lo_unlink(PGconn *conn, Oid lobjId);
<para> <para>
Server-side functions tailored for manipulating large objects from SQL are Server-side functions tailored for manipulating large objects from SQL are
listed in <xref linkend="lo-funcs-table">. listed in <xref linkend="lo-funcs-table"/>.
</para> </para>
<table id="lo-funcs-table"> <table id="lo-funcs-table">
@ -656,7 +656,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image
<caution> <caution>
<para> <para>
It is possible to <xref linkend="sql-grant"> use of the It is possible to <xref linkend="sql-grant"/> use of the
server-side <function>lo_import</function> server-side <function>lo_import</function>
and <function>lo_export</function> functions to non-superusers, but and <function>lo_export</function> functions to non-superusers, but
careful consideration of the security implications is required. A careful consideration of the security implications is required. A
@ -688,7 +688,7 @@ SELECT lo_export(image.raster, '/tmp/motd') FROM image
<title>Example Program</title> <title>Example Program</title>
<para> <para>
<xref linkend="lo-example"> is a sample program which shows how the large object <xref linkend="lo-example"/> is a sample program which shows how the large object
interface interface
in <application>libpq</application> can be used. Parts of the program are in <application>libpq</application> can be used. Parts of the program are
commented out but are left in the source for the reader's commented out but are left in the source for the reader's

28
doc/src/sgml/logical-replication.sgml
View File

@ -8,7 +8,7 @@
changes, based upon their replication identity (usually a primary key). We changes, based upon their replication identity (usually a primary key). We
use the term logical in contrast to physical replication, which uses exact use the term logical in contrast to physical replication, which uses exact
block addresses and byte-by-byte replication. PostgreSQL supports both block addresses and byte-by-byte replication. PostgreSQL supports both
mechanisms concurrently, see <xref linkend="high-availability">. Logical mechanisms concurrently, see <xref linkend="high-availability"/>. Logical
replication allows fine-grained control over both data replication and replication allows fine-grained control over both data replication and
security. security.
</para> </para>
@ -126,7 +126,7 @@
fallback if no other solution is possible. If a replica identity other fallback if no other solution is possible. If a replica identity other
than <quote>full</quote> is set on the publisher side, a replica identity than <quote>full</quote> is set on the publisher side, a replica identity
comprising the same or fewer columns must also be set on the subscriber comprising the same or fewer columns must also be set on the subscriber
side. See <xref linkend="sql-createtable-replica-identity"> for details on side. See <xref linkend="sql-createtable-replica-identity"/> for details on
how to set the replica identity. If a table without a replica identity is how to set the replica identity. If a table without a replica identity is
added to a publication that replicates <command>UPDATE</command> added to a publication that replicates <command>UPDATE</command>
or <command>DELETE</command> operations then or <command>DELETE</command> operations then
@ -140,13 +140,13 @@
</para> </para>
<para> <para>
A publication is created using the <xref linkend="sql-createpublication"> A publication is created using the <xref linkend="sql-createpublication"/>
command and may later be altered or dropped using corresponding commands. command and may later be altered or dropped using corresponding commands.
</para> </para>
<para> <para>
The individual tables can be added and removed dynamically using The individual tables can be added and removed dynamically using
<xref linkend="sql-alterpublication">. Both the <literal>ADD <xref linkend="sql-alterpublication"/>. Both the <literal>ADD
TABLE</literal> and <literal>DROP TABLE</literal> operations are TABLE</literal> and <literal>DROP TABLE</literal> operations are
transactional; so the table will start or stop replicating at the correct transactional; so the table will start or stop replicating at the correct
snapshot once the transaction has committed. snapshot once the transaction has committed.
@ -179,14 +179,14 @@
<para> <para>
Each subscription will receive changes via one replication slot (see Each subscription will receive changes via one replication slot (see
<xref linkend="streaming-replication-slots">). Additional temporary <xref linkend="streaming-replication-slots"/>). Additional temporary
replication slots may be required for the initial data synchronization replication slots may be required for the initial data synchronization
of pre-existing table data. of pre-existing table data.
</para> </para>
<para> <para>
A logical replication subscription can be a standby for synchronous A logical replication subscription can be a standby for synchronous
replication (see <xref linkend="synchronous-replication">). The standby replication (see <xref linkend="synchronous-replication"/>). The standby
name is by default the subscription name. An alternative name can be name is by default the subscription name. An alternative name can be
specified as <literal>application_name</literal> in the connection specified as <literal>application_name</literal> in the connection
information of the subscription. information of the subscription.
@ -200,10 +200,10 @@
</para> </para>
<para> <para>
The subscription is added using <xref linkend="sql-createsubscription"> and The subscription is added using <xref linkend="sql-createsubscription"/> and
can be stopped/resumed at any time using the can be stopped/resumed at any time using the
<xref linkend="sql-altersubscription"> command and removed using <xref linkend="sql-altersubscription"/> command and removed using
<xref linkend="sql-dropsubscription">. <xref linkend="sql-dropsubscription"/>.
</para> </para>
<para> <para>
@ -375,7 +375,7 @@
<listitem> <listitem>
<para> <para>
Large objects (see <xref linkend="largeobjects">) are not replicated. Large objects (see <xref linkend="largeobjects"/>) are not replicated.
There is no workaround for that, other than storing data in normal There is no workaround for that, other than storing data in normal
tables. tables.
</para> </para>
@ -409,13 +409,13 @@
<para> <para>
Logical replication is built with an architecture similar to physical Logical replication is built with an architecture similar to physical
streaming replication (see <xref linkend="streaming-replication">). It is streaming replication (see <xref linkend="streaming-replication"/>). It is
implemented by <quote>walsender</quote> and <quote>apply</quote> implemented by <quote>walsender</quote> and <quote>apply</quote>
processes. The walsender process starts logical decoding (described processes. The walsender process starts logical decoding (described
in <xref linkend="logicaldecoding">) of the WAL and loads the standard in <xref linkend="logicaldecoding"/>) of the WAL and loads the standard
logical decoding plugin (pgoutput). The plugin transforms the changes read logical decoding plugin (pgoutput). The plugin transforms the changes read
from WAL to the logical replication protocol from WAL to the logical replication protocol
(see <xref linkend="protocol-logical-replication">) and filters the data (see <xref linkend="protocol-logical-replication"/>) and filters the data
according to the publication specification. The data is then continuously according to the publication specification. The data is then continuously
transferred using the streaming replication protocol to the apply worker, transferred using the streaming replication protocol to the apply worker,
which maps the data to local tables and applies the individual changes as which maps the data to local tables and applies the individual changes as
@ -461,7 +461,7 @@
<link linkend="streaming-replication">physical streaming replication</link>, <link linkend="streaming-replication">physical streaming replication</link>,
the monitoring on a publication node is similar to monitoring of a the monitoring on a publication node is similar to monitoring of a
physical replication master physical replication master
(see <xref linkend="streaming-replication-monitoring">). (see <xref linkend="streaming-replication-monitoring"/>).
</para> </para>
<para> <para>

44
doc/src/sgml/logicaldecoding.sgml
View File

@ -24,17 +24,17 @@
by <command>INSERT</command> and the new row version created by <command>INSERT</command> and the new row version created
by <command>UPDATE</command>. Availability of old row versions for by <command>UPDATE</command>. Availability of old row versions for
<command>UPDATE</command> and <command>DELETE</command> depends on <command>UPDATE</command> and <command>DELETE</command> depends on
the configured replica identity (see <xref linkend="sql-createtable-replica-identity">). the configured replica identity (see <xref linkend="sql-createtable-replica-identity"/>).
</para> </para>
<para> <para>
Changes can be consumed either using the streaming replication protocol Changes can be consumed either using the streaming replication protocol
(see <xref linkend="protocol-replication"> and (see <xref linkend="protocol-replication"/> and
<xref linkend="logicaldecoding-walsender">), or by calling functions <xref linkend="logicaldecoding-walsender"/>), or by calling functions
via SQL (see <xref linkend="logicaldecoding-sql">). It is also possible via SQL (see <xref linkend="logicaldecoding-sql"/>). It is also possible
to write additional methods of consuming the output of a replication slot to write additional methods of consuming the output of a replication slot
without modifying core code without modifying core code
(see <xref linkend="logicaldecoding-writer">). (see <xref linkend="logicaldecoding-writer"/>).
</para> </para>
<sect1 id="logicaldecoding-example"> <sect1 id="logicaldecoding-example">
@ -47,8 +47,8 @@
<para> <para>
Before you can use logical decoding, you must set Before you can use logical decoding, you must set
<xref linkend="guc-wal-level"> to <literal>logical</literal> and <xref linkend="guc-wal-level"/> to <literal>logical</literal> and
<xref linkend="guc-max-replication-slots"> to at least 1. Then, you <xref linkend="guc-max-replication-slots"/> to at least 1. Then, you
should connect to the target database (in the example should connect to the target database (in the example
below, <literal>postgres</literal>) as a superuser. below, <literal>postgres</literal>) as a superuser.
</para> </para>
@ -146,10 +146,10 @@ postgres=# SELECT pg_drop_replication_slot('regression_slot');
<para> <para>
The following example shows how logical decoding is controlled over the The following example shows how logical decoding is controlled over the
streaming replication protocol, using the streaming replication protocol, using the
program <xref linkend="app-pgrecvlogical"> included in the PostgreSQL program <xref linkend="app-pgrecvlogical"/> included in the PostgreSQL
distribution. This requires that client authentication is set up to allow distribution. This requires that client authentication is set up to allow
replication connections replication connections
(see <xref linkend="streaming-replication-authentication">) and (see <xref linkend="streaming-replication-authentication"/>) and
that <varname>max_wal_senders</varname> is set sufficiently high to allow that <varname>max_wal_senders</varname> is set sufficiently high to allow
an additional connection. an additional connection.
</para> </para>
@ -208,7 +208,7 @@ $ pg_recvlogical -d postgres --slot test --drop-slot
<note> <note>
<para><productname>PostgreSQL</productname> also has streaming replication slots <para><productname>PostgreSQL</productname> also has streaming replication slots
(see <xref linkend="streaming-replication">), but they are used somewhat (see <xref linkend="streaming-replication"/>), but they are used somewhat
differently there. differently there.
</para> </para>
</note> </note>
@ -272,9 +272,9 @@ $ pg_recvlogical -d postgres --slot test --drop-slot
<title>Exported Snapshots</title> <title>Exported Snapshots</title>
<para> <para>
When a new replication slot is created using the streaming replication When a new replication slot is created using the streaming replication
interface (see <xref linkend="protocol-replication-create-slot">), a interface (see <xref linkend="protocol-replication-create-slot"/>), a
snapshot is exported snapshot is exported
(see <xref linkend="functions-snapshot-synchronization">), which will show (see <xref linkend="functions-snapshot-synchronization"/>), which will show
exactly the state of the database after which all changes will be 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 included in the change stream. This can be used to create a new replica by
using <link linkend="sql-set-transaction"><literal>SET TRANSACTION using <link linkend="sql-set-transaction"><literal>SET TRANSACTION
@ -313,11 +313,11 @@ $ pg_recvlogical -d postgres --slot test --drop-slot
are used to create, drop, and stream changes from a replication are used to create, drop, and stream changes from a replication
slot, respectively. These commands are only available over a replication slot, respectively. These commands are only available over a replication
connection; they cannot be used via SQL. connection; they cannot be used via SQL.
See <xref linkend="protocol-replication"> for details on these commands. See <xref linkend="protocol-replication"/> for details on these commands.
</para> </para>
<para> <para>
The command <xref linkend="app-pgrecvlogical"> can be used to control The command <xref linkend="app-pgrecvlogical"/> can be used to control
logical decoding over a streaming replication connection. (It uses logical decoding over a streaming replication connection. (It uses
these commands internally.) these commands internally.)
</para> </para>
@ -327,12 +327,12 @@ $ pg_recvlogical -d postgres --slot test --drop-slot
<title>Logical Decoding <acronym>SQL</acronym> Interface</title> <title>Logical Decoding <acronym>SQL</acronym> Interface</title>
<para> <para>
See <xref linkend="functions-replication"> for detailed documentation on See <xref linkend="functions-replication"/> for detailed documentation on
the SQL-level API for interacting with logical decoding. the SQL-level API for interacting with logical decoding.
</para> </para>
<para> <para>
Synchronous replication (see <xref linkend="synchronous-replication">) is Synchronous replication (see <xref linkend="synchronous-replication"/>) is
only supported on replication slots used over the streaming replication interface. The only supported on replication slots used over the streaming replication interface. The
function interface and additional, non-core interfaces do not support function interface and additional, non-core interfaces do not support
synchronous replication. synchronous replication.
@ -489,7 +489,7 @@ typedef struct OutputPluginOptions
<literal>output_type</literal> has to either be set to <literal>output_type</literal> has to either be set to
<literal>OUTPUT_PLUGIN_TEXTUAL_OUTPUT</literal> <literal>OUTPUT_PLUGIN_TEXTUAL_OUTPUT</literal>
or <literal>OUTPUT_PLUGIN_BINARY_OUTPUT</literal>. See also or <literal>OUTPUT_PLUGIN_BINARY_OUTPUT</literal>. See also
<xref linkend="logicaldecoding-output-mode">. <xref linkend="logicaldecoding-output-mode"/>.
</para> </para>
<para> <para>
@ -576,8 +576,8 @@ typedef void (*LogicalDecodeChangeCB) (struct LogicalDecodingContext *ctx,
<note> <note>
<para> <para>
Only changes in user defined tables that are not unlogged Only changes in user defined tables that are not unlogged
(see <xref linkend="sql-createtable-unlogged">) and not temporary (see <xref linkend="sql-createtable-unlogged"/>) and not temporary
(see <xref linkend="sql-createtable-temporary">) can be extracted using (see <xref linkend="sql-createtable-temporary"/>) can be extracted using
logical decoding. logical decoding.
</para> </para>
</note> </note>
@ -685,7 +685,7 @@ OutputPluginWrite(ctx, true);
<filename>src/backend/replication/logical/logicalfuncs.c</filename>. <filename>src/backend/replication/logical/logicalfuncs.c</filename>.
Essentially, three functions need to be provided: one to read WAL, one to Essentially, three functions need to be provided: one to read WAL, one to
prepare writing output, and one to write the output prepare writing output, and one to write the output
(see <xref linkend="logicaldecoding-output-plugin-output">). (see <xref linkend="logicaldecoding-output-plugin-output"/>).
</para> </para>
</sect1> </sect1>
@ -698,9 +698,9 @@ OutputPluginWrite(ctx, true);
replication</link> solutions with the same user interface as synchronous replication</link> solutions with the same user interface as synchronous
replication for <link linkend="streaming-replication">streaming replication for <link linkend="streaming-replication">streaming
replication</link>. To do this, the streaming replication interface replication</link>. To do this, the streaming replication interface
(see <xref linkend="logicaldecoding-walsender">) must be used to stream out (see <xref linkend="logicaldecoding-walsender"/>) must be used to stream out
data. Clients have to send <literal>Standby status update (F)</literal> data. Clients have to send <literal>Standby status update (F)</literal>
(see <xref linkend="protocol-replication">) messages, just like streaming (see <xref linkend="protocol-replication"/>) messages, just like streaming
replication clients do. replication clients do.
</para> </para>

6
doc/src/sgml/ltree.sgml
View File

@ -183,7 +183,7 @@ Europe &amp; Russia*@ &amp; !Transportation
<literal>&lt;</literal>, <literal>&gt;</literal>, <literal>&lt;=</literal>, <literal>&gt;=</literal>. <literal>&lt;</literal>, <literal>&gt;</literal>, <literal>&lt;=</literal>, <literal>&gt;=</literal>.
Comparison sorts in the order of a tree traversal, with the children Comparison sorts in the order of a tree traversal, with the children
of a node sorted by label text. In addition, the specialized of a node sorted by label text. In addition, the specialized
operators shown in <xref linkend="ltree-op-table"> are available. operators shown in <xref linkend="ltree-op-table"/> are available.
</para> </para>
<table id="ltree-op-table"> <table id="ltree-op-table">
@ -362,7 +362,7 @@ Europe &amp; Russia*@ &amp; !Transportation
</para> </para>
<para> <para>
The available functions are shown in <xref linkend="ltree-func-table">. The available functions are shown in <xref linkend="ltree-func-table"/>.
</para> </para>
<table id="ltree-func-table"> <table id="ltree-func-table">
@ -672,7 +672,7 @@ ltreetest=&gt; SELECT ins_label(path,2,'Space') FROM test WHERE path &lt;@ 'Top.
the <type>ltree</type> type for PL/Python. The extensions are the <type>ltree</type> type for PL/Python. The extensions are
called <literal>ltree_plpythonu</literal>, <literal>ltree_plpython2u</literal>, called <literal>ltree_plpythonu</literal>, <literal>ltree_plpython2u</literal>,
and <literal>ltree_plpython3u</literal> and <literal>ltree_plpython3u</literal>
(see <xref linkend="plpython-python23"> for the PL/Python naming (see <xref linkend="plpython-python23"/> for the PL/Python naming
convention). If you install these transforms and specify them when convention). If you install these transforms and specify them when
creating a function, <type>ltree</type> values are mapped to Python lists. creating a function, <type>ltree</type> values are mapped to Python lists.
(The reverse is currently not supported, however.) (The reverse is currently not supported, however.)

80
doc/src/sgml/maintenance.sgml
View File

@ -28,20 +28,20 @@
after a catastrophe (disk failure, fire, mistakenly dropping a critical after a catastrophe (disk failure, fire, mistakenly dropping a critical
table, etc.). The backup and recovery mechanisms available in table, etc.). The backup and recovery mechanisms available in
<productname>PostgreSQL</productname> are discussed at length in <productname>PostgreSQL</productname> are discussed at length in
<xref linkend="backup">. <xref linkend="backup"/>.
</para> </para>
<para> <para>
The other main category of maintenance task is periodic <quote>vacuuming</quote> The other main category of maintenance task is periodic <quote>vacuuming</quote>
of the database. This activity is discussed in of the database. This activity is discussed in
<xref linkend="routine-vacuuming">. Closely related to this is updating <xref linkend="routine-vacuuming"/>. Closely related to this is updating
the statistics that will be used by the query planner, as discussed in the statistics that will be used by the query planner, as discussed in
<xref linkend="vacuum-for-statistics">. <xref linkend="vacuum-for-statistics"/>.
</para> </para>
<para> <para>
Another task that might need periodic attention is log file management. Another task that might need periodic attention is log file management.
This is discussed in <xref linkend="logfile-maintenance">. This is discussed in <xref linkend="logfile-maintenance"/>.
</para> </para>
<para> <para>
@ -70,7 +70,7 @@
<productname>PostgreSQL</productname> databases require periodic <productname>PostgreSQL</productname> databases require periodic
maintenance known as <firstterm>vacuuming</firstterm>. For many installations, it maintenance known as <firstterm>vacuuming</firstterm>. For many installations, it
is sufficient to let vacuuming be performed by the <firstterm>autovacuum is sufficient to let vacuuming be performed by the <firstterm>autovacuum
daemon</firstterm>, which is described in <xref linkend="autovacuum">. You might daemon</firstterm>, which is described in <xref linkend="autovacuum"/>. You might
need to adjust the autovacuuming parameters described there to obtain best need to adjust the autovacuuming parameters described there to obtain best
results for your situation. Some database administrators will want to results for your situation. Some database administrators will want to
supplement or replace the daemon's activities with manually-managed supplement or replace the daemon's activities with manually-managed
@ -87,7 +87,7 @@
<para> <para>
<productname>PostgreSQL</productname>'s <productname>PostgreSQL</productname>'s
<xref linkend="sql-vacuum"> command has to <xref linkend="sql-vacuum"/> command has to
process each table on a regular basis for several reasons: process each table on a regular basis for several reasons:
<orderedlist> <orderedlist>
@ -140,7 +140,7 @@
traffic, which can cause poor performance for other active sessions. traffic, which can cause poor performance for other active sessions.
There are configuration parameters that can be adjusted to reduce the There are configuration parameters that can be adjusted to reduce the
performance impact of background vacuuming &mdash; see performance impact of background vacuuming &mdash; see
<xref linkend="runtime-config-resource-vacuum-cost">. <xref linkend="runtime-config-resource-vacuum-cost"/>.
</para> </para>
</sect2> </sect2>
@ -156,7 +156,7 @@
<command>UPDATE</command> or <command>DELETE</command> of a row does not <command>UPDATE</command> or <command>DELETE</command> of a row does not
immediately remove the old version of the row. immediately remove the old version of the row.
This approach is necessary to gain the benefits of multiversion This approach is necessary to gain the benefits of multiversion
concurrency control (<acronym>MVCC</acronym>, see <xref linkend="mvcc">): the row version concurrency control (<acronym>MVCC</acronym>, see <xref linkend="mvcc"/>): the row version
must not be deleted while it is still potentially visible to other must not be deleted while it is still potentially visible to other
transactions. But eventually, an outdated or deleted row version is no transactions. But eventually, an outdated or deleted row version is no
longer of interest to any transaction. The space it occupies must then be longer of interest to any transaction. The space it occupies must then be
@ -217,7 +217,7 @@
their busiest tables as often as once every few minutes.) If you have their busiest tables as often as once every few minutes.) If you have
multiple databases in a cluster, don't forget to multiple databases in a cluster, don't forget to
<command>VACUUM</command> each one; the program <xref <command>VACUUM</command> each one; the program <xref
linkend="app-vacuumdb"> might be helpful. linkend="app-vacuumdb"/> might be helpful.
</para> </para>
<tip> <tip>
@ -227,9 +227,9 @@
massive update or delete activity. If you have such a table and massive update or delete activity. If you have such a table and
you need to reclaim the excess disk space it occupies, you will need you need to reclaim the excess disk space it occupies, you will need
to use <command>VACUUM FULL</command>, or alternatively to use <command>VACUUM FULL</command>, or alternatively
<xref linkend="sql-cluster"> <xref linkend="sql-cluster"/>
or one of the table-rewriting variants of or one of the table-rewriting variants of
<xref linkend="sql-altertable">. <xref linkend="sql-altertable"/>.
These commands rewrite an entire new copy of the table and build These commands rewrite an entire new copy of the table and build
new indexes for it. All these options require exclusive lock. Note that new indexes for it. All these options require exclusive lock. Note that
they also temporarily use extra disk space approximately equal to the size they also temporarily use extra disk space approximately equal to the size
@ -242,7 +242,7 @@
<para> <para>
If you have a table whose entire contents are deleted on a periodic If you have a table whose entire contents are deleted on a periodic
basis, consider doing it with basis, consider doing it with
<xref linkend="sql-truncate"> rather <xref linkend="sql-truncate"/> rather
than using <command>DELETE</command> followed by than using <command>DELETE</command> followed by
<command>VACUUM</command>. <command>TRUNCATE</command> removes the <command>VACUUM</command>. <command>TRUNCATE</command> removes the
entire content of the table immediately, without requiring a entire content of the table immediately, without requiring a
@ -269,7 +269,7 @@
The <productname>PostgreSQL</productname> query planner relies on The <productname>PostgreSQL</productname> query planner relies on
statistical information about the contents of tables in order to statistical information about the contents of tables in order to
generate good plans for queries. These statistics are gathered by generate good plans for queries. These statistics are gathered by
the <xref linkend="sql-analyze"> command, the <xref linkend="sql-analyze"/> command,
which can be invoked by itself or which can be invoked by itself or
as an optional step in <command>VACUUM</command>. It is important to have as an optional step in <command>VACUUM</command>. It is important to have
reasonably accurate statistics, otherwise poor choices of plans might reasonably accurate statistics, otherwise poor choices of plans might
@ -323,7 +323,7 @@
clauses and have highly irregular data distributions might require a clauses and have highly irregular data distributions might require a
finer-grain data histogram than other columns. See <command>ALTER TABLE finer-grain data histogram than other columns. See <command>ALTER TABLE
SET STATISTICS</command>, or change the database-wide default using the <xref SET STATISTICS</command>, or change the database-wide default using the <xref
linkend="guc-default-statistics-target"> configuration parameter. linkend="guc-default-statistics-target"/> configuration parameter.
</para> </para>
<para> <para>
@ -453,7 +453,7 @@
</note> </note>
<para> <para>
<xref linkend="guc-vacuum-freeze-min-age"> <xref linkend="guc-vacuum-freeze-min-age"/>
controls how old an XID value has to be before rows bearing that XID 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 frozen. Increasing this setting may avoid unnecessary work if the
rows that would otherwise be frozen will soon be modified again, rows that would otherwise be frozen will soon be modified again,
@ -471,7 +471,7 @@
Periodically, <command>VACUUM</command> will perform an <firstterm>aggressive Periodically, <command>VACUUM</command> will perform an <firstterm>aggressive
vacuum</firstterm>, skipping only those pages which contain neither dead rows nor vacuum</firstterm>, skipping only those pages which contain neither dead rows nor
any unfrozen XID or MXID values. any unfrozen XID or MXID values.
<xref linkend="guc-vacuum-freeze-table-age"> <xref linkend="guc-vacuum-freeze-table-age"/>
controls when <command>VACUUM</command> does that: all-visible but not all-frozen controls when <command>VACUUM</command> does that: all-visible but not all-frozen
pages are scanned if the number of transactions that have passed since the pages are scanned if the number of transactions that have passed since the
last such scan is greater than <varname>vacuum_freeze_table_age</varname> minus last such scan is greater than <varname>vacuum_freeze_table_age</varname> minus
@ -488,7 +488,7 @@
that, data loss could result. To ensure that this does not happen, that, data loss could result. To ensure that this does not happen,
autovacuum is invoked on any table that might contain unfrozen rows with autovacuum is invoked on any table that might contain unfrozen rows with
XIDs older than the age specified by the configuration parameter <xref XIDs older than the age specified by the configuration parameter <xref
linkend="guc-autovacuum-freeze-max-age">. (This will happen even if linkend="guc-autovacuum-freeze-max-age"/>. (This will happen even if
autovacuum is disabled.) autovacuum is disabled.)
</para> </para>
@ -636,7 +636,7 @@ HINT: Stop the postmaster and vacuum that database in single-user mode.
execute commands once it has gone into the safety shutdown mode, execute commands once it has gone into the safety shutdown mode,
the only way to do this is to stop the server and start the server in single-user the only way to do this is to stop the server and start the server in single-user
mode to execute <command>VACUUM</command>. The shutdown mode is not enforced mode to execute <command>VACUUM</command>. The shutdown mode is not enforced
in single-user mode. See the <xref linkend="app-postgres"> reference in single-user mode. See the <xref linkend="app-postgres"/> reference
page for details about using single-user mode. page for details about using single-user mode.
</para> </para>
@ -673,13 +673,13 @@ HINT: Stop the postmaster and vacuum that database in single-user mode.
<para> <para>
Whenever <command>VACUUM</command> scans any part of a table, it will replace Whenever <command>VACUUM</command> scans any part of a table, it will replace
any multixact ID it encounters which is older than any multixact ID it encounters which is older than
<xref linkend="guc-vacuum-multixact-freeze-min-age"> <xref linkend="guc-vacuum-multixact-freeze-min-age"/>
by a different value, which can be the zero value, a single by a different value, which can be the zero value, a single
transaction ID, or a newer multixact ID. For each table, transaction ID, or a newer multixact ID. For each table,
<structname>pg_class</structname>.<structfield>relminmxid</structfield> stores the oldest <structname>pg_class</structname>.<structfield>relminmxid</structfield> stores the oldest
possible multixact ID still appearing in any tuple of that table. possible multixact ID still appearing in any tuple of that table.
If this value is older than If this value is older than
<xref linkend="guc-vacuum-multixact-freeze-table-age">, an aggressive <xref linkend="guc-vacuum-multixact-freeze-table-age"/>, an aggressive
vacuum is forced. As discussed in the previous section, an aggressive vacuum is forced. As discussed in the previous section, an aggressive
vacuum means that only those pages which are known to be all-frozen will vacuum means that only those pages which are known to be all-frozen will
be skipped. <function>mxid_age()</function> can be used on be skipped. <function>mxid_age()</function> can be used on
@ -697,7 +697,7 @@ HINT: Stop the postmaster and vacuum that database in single-user mode.
<para> <para>
As a safety device, an aggressive vacuum scan will occur for any table As a safety device, an aggressive vacuum scan will occur for any table
whose multixact-age is greater than whose multixact-age is greater than
<xref linkend="guc-autovacuum-multixact-freeze-max-age">. Aggressive <xref linkend="guc-autovacuum-multixact-freeze-max-age"/>. Aggressive
vacuum scans will also occur progressively for all tables, starting with vacuum scans will also occur progressively for all tables, starting with
those that have the oldest multixact-age, if the amount of used member those that have the oldest multixact-age, if the amount of used member
storage space exceeds the amount 50% of the addressable storage space. storage space exceeds the amount 50% of the addressable storage space.
@ -723,7 +723,7 @@ HINT: Stop the postmaster and vacuum that database in single-user mode.
tables that have had a large number of inserted, updated or deleted tables that have had a large number of inserted, updated or deleted
tuples. These checks use the statistics collection facility; tuples. These checks use the statistics collection facility;
therefore, autovacuum cannot be used unless <xref therefore, autovacuum cannot be used unless <xref
linkend="guc-track-counts"> is set to <literal>true</literal>. linkend="guc-track-counts"/> is set to <literal>true</literal>.
In the default configuration, autovacuuming is enabled and the related In the default configuration, autovacuuming is enabled and the related
configuration parameters are appropriately set. configuration parameters are appropriately set.
</para> </para>
@ -734,17 +734,17 @@ HINT: Stop the postmaster and vacuum that database in single-user mode.
<firstterm>autovacuum launcher</firstterm>, which is in charge of starting <firstterm>autovacuum launcher</firstterm>, which is in charge of starting
<firstterm>autovacuum worker</firstterm> processes for all databases. The <firstterm>autovacuum worker</firstterm> processes for all databases. The
launcher will distribute the work across time, attempting to start one launcher will distribute the work across time, attempting to start one
worker within each database every <xref linkend="guc-autovacuum-naptime"> worker within each database every <xref linkend="guc-autovacuum-naptime"/>
seconds. (Therefore, if the installation has <replaceable>N</replaceable> databases, seconds. (Therefore, if the installation has <replaceable>N</replaceable> databases,
a new worker will be launched every a new worker will be launched every
<varname>autovacuum_naptime</varname>/<replaceable>N</replaceable> seconds.) <varname>autovacuum_naptime</varname>/<replaceable>N</replaceable> seconds.)
A maximum of <xref linkend="guc-autovacuum-max-workers"> worker processes A maximum of <xref linkend="guc-autovacuum-max-workers"/> worker processes
are allowed to run at the same time. If there are more than are allowed to run at the same time. If there are more than
<varname>autovacuum_max_workers</varname> databases to be processed, <varname>autovacuum_max_workers</varname> databases to be processed,
the next database will be processed as soon as the first worker finishes. the next database will be processed as soon as the first worker finishes.
Each worker process will check each table within its database and Each worker process will check each table within its database and
execute <command>VACUUM</command> and/or <command>ANALYZE</command> as needed. execute <command>VACUUM</command> and/or <command>ANALYZE</command> as needed.
<xref linkend="guc-log-autovacuum-min-duration"> can be set to monitor <xref linkend="guc-log-autovacuum-min-duration"/> can be set to monitor
autovacuum workers' activity. autovacuum workers' activity.
</para> </para>
@ -756,13 +756,13 @@ HINT: Stop the postmaster and vacuum that database in single-user mode.
available. There is no limit on how many workers might be in a available. There is no limit on how many workers might be in a
single database, but workers do try to avoid repeating work that has single database, but workers do try to avoid repeating work that has
already been done by other workers. Note that the number of running already been done by other workers. Note that the number of running
workers does not count towards <xref linkend="guc-max-connections"> or workers does not count towards <xref linkend="guc-max-connections"/> or
<xref linkend="guc-superuser-reserved-connections"> limits. <xref linkend="guc-superuser-reserved-connections"/> limits.
</para> </para>
<para> <para>
Tables whose <structfield>relfrozenxid</structfield> value is more than Tables whose <structfield>relfrozenxid</structfield> value is more than
<xref linkend="guc-autovacuum-freeze-max-age"> transactions old are always <xref linkend="guc-autovacuum-freeze-max-age"/> transactions old are always
vacuumed (this also applies to those tables whose freeze max age has vacuumed (this also applies to those tables whose freeze max age has
been modified via storage parameters; see below). Otherwise, if the been modified via storage parameters; see below). Otherwise, if the
number of tuples obsoleted since the last number of tuples obsoleted since the last
@ -772,9 +772,9 @@ HINT: Stop the postmaster and vacuum that database in single-user mode.
vacuum threshold = vacuum base threshold + vacuum scale factor * number of tuples vacuum threshold = vacuum base threshold + vacuum scale factor * number of tuples
</programlisting> </programlisting>
where the vacuum base threshold is where the vacuum base threshold is
<xref linkend="guc-autovacuum-vacuum-threshold">, <xref linkend="guc-autovacuum-vacuum-threshold"/>,
the vacuum scale factor is the vacuum scale factor is
<xref linkend="guc-autovacuum-vacuum-scale-factor">, <xref linkend="guc-autovacuum-vacuum-scale-factor"/>,
and the number of tuples is and the number of tuples is
<structname>pg_class</structname>.<structfield>reltuples</structfield>. <structname>pg_class</structname>.<structfield>reltuples</structfield>.
The number of obsolete tuples is obtained from the statistics The number of obsolete tuples is obtained from the statistics
@ -808,16 +808,16 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
<filename>postgresql.conf</filename>, but it is possible to override them <filename>postgresql.conf</filename>, but it is possible to override them
(and many other autovacuum control parameters) on a per-table basis; see (and many other autovacuum control parameters) on a per-table basis; see
<xref linkend="sql-createtable-storage-parameters" <xref linkend="sql-createtable-storage-parameters"
endterm="sql-createtable-storage-parameters-title"> for more information. endterm="sql-createtable-storage-parameters-title"/> for more information.
If a setting has been changed via a table's storage parameters, that value If a setting has been changed via a table's storage parameters, that value
is used when processing that table; otherwise the global settings are is used when processing that table; otherwise the global settings are
used. See <xref linkend="runtime-config-autovacuum"> for more details on used. See <xref linkend="runtime-config-autovacuum"/> for more details on
the global settings. the global settings.
</para> </para>
<para> <para>
When multiple workers are running, the autovacuum cost delay parameters When multiple workers are running, the autovacuum cost delay parameters
(see <xref linkend="runtime-config-resource-vacuum-cost">) are (see <xref linkend="runtime-config-resource-vacuum-cost"/>) are
<quote>balanced</quote> among all the running workers, so that the <quote>balanced</quote> among all the running workers, so that the
total I/O impact on the system is the same regardless of the number total I/O impact on the system is the same regardless of the number
of workers actually running. However, any workers processing tables whose of workers actually running. However, any workers processing tables whose
@ -838,7 +838,7 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
<para> <para>
In some situations it is worthwhile to rebuild indexes periodically In some situations it is worthwhile to rebuild indexes periodically
with the <xref linkend="sql-reindex"> command or a series of individual with the <xref linkend="sql-reindex"/> command or a series of individual
rebuilding steps. rebuilding steps.
</para> </para>
@ -868,16 +868,16 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
</para> </para>
<para> <para>
<xref linkend="sql-reindex"> can be used safely and easily in all cases. <xref linkend="sql-reindex"/> can be used safely and easily in all cases.
But since the command requires an exclusive table lock, it is But since the command requires an exclusive table lock, it is
often preferable to execute an index rebuild with a sequence of often preferable to execute an index rebuild with a sequence of
creation and replacement steps. Index types that support creation and replacement steps. Index types that support
<xref linkend="sql-createindex"> with the <literal>CONCURRENTLY</literal> <xref linkend="sql-createindex"/> with the <literal>CONCURRENTLY</literal>
option can instead be recreated that way. If that is successful and the option can instead be recreated that way. If that is successful and the
resulting index is valid, the original index can then be replaced by resulting index is valid, the original index can then be replaced by
the newly built one using a combination of <xref linkend="sql-alterindex"> the newly built one using a combination of <xref linkend="sql-alterindex"/>
and <xref linkend="sql-dropindex">. When an index is used to enforce and <xref linkend="sql-dropindex"/>. When an index is used to enforce
uniqueness or other constraints, <xref linkend="sql-altertable"> might uniqueness or other constraints, <xref linkend="sql-altertable"/> might
be necessary to swap the existing constraint with one enforced by be necessary to swap the existing constraint with one enforced by
the new index. Review this alternate multistep rebuild approach the new index. Review this alternate multistep rebuild approach
carefully before using it as there are limitations on which carefully before using it as there are limitations on which
@ -922,7 +922,7 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
setting the configuration parameter <varname>logging_collector</varname> to setting the configuration parameter <varname>logging_collector</varname> to
<literal>true</literal> in <filename>postgresql.conf</filename>. The control <literal>true</literal> in <filename>postgresql.conf</filename>. The control
parameters for this program are described in <xref parameters for this program are described in <xref
linkend="runtime-config-logging-where">. You can also use this approach linkend="runtime-config-logging-where"/>. You can also use this approach
to capture the log data in machine readable <acronym>CSV</acronym> to capture the log data in machine readable <acronym>CSV</acronym>
(comma-separated values) format. (comma-separated values) format.
</para> </para>

38
doc/src/sgml/manage-ag.sgml
View File

@ -49,20 +49,20 @@
resources, they should be put in the same database but possibly resources, they should be put in the same database but possibly
into separate schemas. Schemas are a purely logical structure and who can into separate schemas. Schemas are a purely logical structure and who can
access what is managed by the privilege system. More information about access what is managed by the privilege system. More information about
managing schemas is in <xref linkend="ddl-schemas">. managing schemas is in <xref linkend="ddl-schemas"/>.
</para> </para>
<para> <para>
Databases are created with the <command>CREATE DATABASE</command> command Databases are created with the <command>CREATE DATABASE</command> command
(see <xref linkend="manage-ag-createdb">) and destroyed with the (see <xref linkend="manage-ag-createdb"/>) and destroyed with the
<command>DROP DATABASE</command> command <command>DROP DATABASE</command> command
(see <xref linkend="manage-ag-dropdb">). (see <xref linkend="manage-ag-dropdb"/>).
To determine the set of existing databases, examine the To determine the set of existing databases, examine the
<structname>pg_database</structname> system catalog, for example <structname>pg_database</structname> system catalog, for example
<synopsis> <synopsis>
SELECT datname FROM pg_database; SELECT datname FROM pg_database;
</synopsis> </synopsis>
The <xref linkend="app-psql"> program's <literal>\l</literal> meta-command The <xref linkend="app-psql"/> program's <literal>\l</literal> meta-command
and <option>-l</option> command-line option are also useful for listing the and <option>-l</option> command-line option are also useful for listing the
existing databases. existing databases.
</para> </para>
@ -83,12 +83,12 @@ SELECT datname FROM pg_database;
<para> <para>
In order to create a database, the <productname>PostgreSQL</productname> In order to create a database, the <productname>PostgreSQL</productname>
server must be up and running (see <xref server must be up and running (see <xref
linkend="server-start">). linkend="server-start"/>).
</para> </para>
<para> <para>
Databases are created with the SQL command Databases are created with the SQL command
<xref linkend="sql-createdatabase">: <xref linkend="sql-createdatabase"/>:
<synopsis> <synopsis>
CREATE DATABASE <replaceable>name</replaceable>; CREATE DATABASE <replaceable>name</replaceable>;
</synopsis> </synopsis>
@ -101,7 +101,7 @@ CREATE DATABASE <replaceable>name</replaceable>;
<para> <para>
The creation of databases is a restricted operation. See <xref The creation of databases is a restricted operation. See <xref
linkend="role-attributes"> for how to grant permission. linkend="role-attributes"/> for how to grant permission.
</para> </para>
<para> <para>
@ -110,7 +110,7 @@ CREATE DATABASE <replaceable>name</replaceable>;
question remains how the <emphasis>first</emphasis> database at any given question remains how the <emphasis>first</emphasis> database at any given
site can be created. The first database is always created by the site can be created. The first database is always created by the
<command>initdb</command> command when the data storage area is <command>initdb</command> command when the data storage area is
initialized. (See <xref linkend="creating-cluster">.) This initialized. (See <xref linkend="creating-cluster"/>.) This
database is called database is called
<literal>postgres</literal>.<indexterm><primary>postgres</primary></indexterm> So to <literal>postgres</literal>.<indexterm><primary>postgres</primary></indexterm> So to
create the first <quote>ordinary</quote> database you can connect to create the first <quote>ordinary</quote> database you can connect to
@ -127,7 +127,7 @@ CREATE DATABASE <replaceable>name</replaceable>;
propagated to all subsequently created databases. Because of this, propagated to all subsequently created databases. Because of this,
avoid creating objects in <literal>template1</literal> unless you want them avoid creating objects in <literal>template1</literal> unless you want them
propagated to every newly created database. More details propagated to every newly created database. More details
appear in <xref linkend="manage-ag-templatedbs">. appear in <xref linkend="manage-ag-templatedbs"/>.
</para> </para>
<para> <para>
@ -142,14 +142,14 @@ createdb <replaceable class="parameter">dbname</replaceable>
<command>createdb</command> does no magic. It connects to the <literal>postgres</literal> <command>createdb</command> does no magic. It connects to the <literal>postgres</literal>
database and issues the <command>CREATE DATABASE</command> command, database and issues the <command>CREATE DATABASE</command> command,
exactly as described above. exactly as described above.
The <xref linkend="app-createdb"> reference page contains the invocation The <xref linkend="app-createdb"/> reference page contains the invocation
details. Note that <command>createdb</command> without any arguments will create details. Note that <command>createdb</command> without any arguments will create
a database with the current user name. a database with the current user name.
</para> </para>
<note> <note>
<para> <para>
<xref linkend="client-authentication"> contains information about <xref linkend="client-authentication"/> contains information about
how to restrict who can connect to a given database. how to restrict who can connect to a given database.
</para> </para>
</note> </note>
@ -283,7 +283,7 @@ createdb -T template0 <replaceable>dbname</replaceable>
<title>Database Configuration</title> <title>Database Configuration</title>
<para> <para>
Recall from <xref linkend="runtime-config"> that the Recall from <xref linkend="runtime-config"/> that the
<productname>PostgreSQL</productname> server provides a large number of <productname>PostgreSQL</productname> server provides a large number of
run-time configuration variables. You can set database-specific run-time configuration variables. You can set database-specific
default values for many of these settings. default values for many of these settings.
@ -315,7 +315,7 @@ ALTER DATABASE mydb SET geqo TO off;
<para> <para>
Databases are destroyed with the command Databases are destroyed with the command
<xref linkend="sql-dropdatabase">:<indexterm><primary>DROP DATABASE</primary></indexterm> <xref linkend="sql-dropdatabase"/>:<indexterm><primary>DROP DATABASE</primary></indexterm>
<synopsis> <synopsis>
DROP DATABASE <replaceable>name</replaceable>; DROP DATABASE <replaceable>name</replaceable>;
</synopsis> </synopsis>
@ -337,7 +337,7 @@ DROP DATABASE <replaceable>name</replaceable>;
<para> <para>
For convenience, there is also a shell program to drop For convenience, there is also a shell program to drop
databases, <xref linkend="app-dropdb">:<indexterm><primary>dropdb</primary></indexterm> databases, <xref linkend="app-dropdb"/>:<indexterm><primary>dropdb</primary></indexterm>
<synopsis> <synopsis>
dropdb <replaceable class="parameter">dbname</replaceable> dropdb <replaceable class="parameter">dbname</replaceable>
</synopsis> </synopsis>
@ -396,7 +396,7 @@ dropdb <replaceable class="parameter">dbname</replaceable>
<para> <para>
To define a tablespace, use the <xref To define a tablespace, use the <xref
linkend="sql-createtablespace"> linkend="sql-createtablespace"/>
command, for example:<indexterm><primary>CREATE TABLESPACE</primary></indexterm>: command, for example:<indexterm><primary>CREATE TABLESPACE</primary></indexterm>:
<programlisting> <programlisting>
CREATE TABLESPACE fastspace LOCATION '/ssd1/postgresql/data'; CREATE TABLESPACE fastspace LOCATION '/ssd1/postgresql/data';
@ -438,7 +438,7 @@ CREATE TABLE foo(i int) TABLESPACE space1;
</para> </para>
<para> <para>
Alternatively, use the <xref linkend="guc-default-tablespace"> parameter: Alternatively, use the <xref linkend="guc-default-tablespace"/> parameter:
<programlisting> <programlisting>
SET default_tablespace = space1; SET default_tablespace = space1;
CREATE TABLE foo(i int); CREATE TABLE foo(i int);
@ -450,7 +450,7 @@ CREATE TABLE foo(i int);
</para> </para>
<para> <para>
There is also a <xref linkend="guc-temp-tablespaces"> parameter, which There is also a <xref linkend="guc-temp-tablespaces"/> parameter, which
determines the placement of temporary tables and indexes, as well as determines the placement of temporary tables and indexes, as well as
temporary files that are used for purposes such as sorting large data temporary files that are used for purposes such as sorting large data
sets. This can be a list of tablespace names, rather than only one, sets. This can be a list of tablespace names, rather than only one,
@ -490,7 +490,7 @@ CREATE TABLE foo(i int);
<para> <para>
To remove an empty tablespace, use the <xref To remove an empty tablespace, use the <xref
linkend="sql-droptablespace"> linkend="sql-droptablespace"/>
command. command.
</para> </para>
@ -501,7 +501,7 @@ CREATE TABLE foo(i int);
<synopsis> <synopsis>
SELECT spcname FROM pg_tablespace; SELECT spcname FROM pg_tablespace;
</synopsis> </synopsis>
The <xref linkend="app-psql"> program's <literal>\db</literal> meta-command The <xref linkend="app-psql"/> program's <literal>\db</literal> meta-command
is also useful for listing the existing tablespaces. is also useful for listing the existing tablespaces.
</para> </para>

108
doc/src/sgml/monitoring.sgml
View File

@ -27,8 +27,8 @@
<command>ps</command>, <command>top</command>, <command>iostat</command>, and <command>vmstat</command>. <command>ps</command>, <command>top</command>, <command>iostat</command>, and <command>vmstat</command>.
Also, once one has identified a Also, once one has identified a
poorly-performing query, further investigation might be needed using poorly-performing query, further investigation might be needed using
<productname>PostgreSQL</productname>'s <xref linkend="sql-explain"> command. <productname>PostgreSQL</productname>'s <xref linkend="sql-explain"/> command.
<xref linkend="using-explain"> discusses <command>EXPLAIN</command> <xref linkend="using-explain"/> discusses <command>EXPLAIN</command>
and other methods for understanding the behavior of an individual and other methods for understanding the behavior of an individual
query. query.
</para> </para>
@ -92,7 +92,7 @@ postgres: <replaceable>user</replaceable> <replaceable>database</replaceable> <r
</para> </para>
<para> <para>
If <xref linkend="guc-cluster-name"> has been configured the If <xref linkend="guc-cluster-name"/> has been configured the
cluster name will also be shown in <command>ps</command> output: cluster name will also be shown in <command>ps</command> output:
<screen> <screen>
$ psql -c 'SHOW cluster_name' $ psql -c 'SHOW cluster_name'
@ -108,7 +108,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
</para> </para>
<para> <para>
If you have turned off <xref linkend="guc-update-process-title"> then the If you have turned off <xref linkend="guc-update-process-title"/> then the
activity indicator is not updated; the process title is set only once activity indicator is not updated; the process title is set only once
when a new process is launched. On some platforms this saves a measurable when a new process is launched. On some platforms this saves a measurable
amount of per-command overhead; on others it's insignificant. amount of per-command overhead; on others it's insignificant.
@ -161,27 +161,27 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
Since collection of statistics adds some overhead to query execution, Since collection of statistics adds some overhead to query execution,
the system can be configured to collect or not collect information. the system can be configured to collect or not collect information.
This is controlled by configuration parameters that are normally set in This is controlled by configuration parameters that are normally set in
<filename>postgresql.conf</filename>. (See <xref linkend="runtime-config"> for <filename>postgresql.conf</filename>. (See <xref linkend="runtime-config"/> for
details about setting configuration parameters.) details about setting configuration parameters.)
</para> </para>
<para> <para>
The parameter <xref linkend="guc-track-activities"> enables monitoring The parameter <xref linkend="guc-track-activities"/> enables monitoring
of the current command being executed by any server process. of the current command being executed by any server process.
</para> </para>
<para> <para>
The parameter <xref linkend="guc-track-counts"> controls whether The parameter <xref linkend="guc-track-counts"/> controls whether
statistics are collected about table and index accesses. statistics are collected about table and index accesses.
</para> </para>
<para> <para>
The parameter <xref linkend="guc-track-functions"> enables tracking of The parameter <xref linkend="guc-track-functions"/> enables tracking of
usage of user-defined functions. usage of user-defined functions.
</para> </para>
<para> <para>
The parameter <xref linkend="guc-track-io-timing"> enables monitoring The parameter <xref linkend="guc-track-io-timing"/> enables monitoring
of block read and write times. of block read and write times.
</para> </para>
@ -189,7 +189,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
Normally these parameters are set in <filename>postgresql.conf</filename> so Normally these parameters are set in <filename>postgresql.conf</filename> so
that they apply to all server processes, but it is possible to turn that they apply to all server processes, but it is possible to turn
them on or off in individual sessions using the <xref them on or off in individual sessions using the <xref
linkend="sql-set"> command. (To prevent linkend="sql-set"/> command. (To prevent
ordinary users from hiding their activity from the administrator, ordinary users from hiding their activity from the administrator,
only superusers are allowed to change these parameters with only superusers are allowed to change these parameters with
<command>SET</command>.) <command>SET</command>.)
@ -199,7 +199,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
The statistics collector transmits the collected information to other The statistics collector transmits the collected information to other
<productname>PostgreSQL</productname> processes through temporary files. <productname>PostgreSQL</productname> processes through temporary files.
These files are stored in the directory named by the These files are stored in the directory named by the
<xref linkend="guc-stats-temp-directory"> parameter, <xref linkend="guc-stats-temp-directory"/> parameter,
<filename>pg_stat_tmp</filename> by default. <filename>pg_stat_tmp</filename> by default.
For better performance, <varname>stats_temp_directory</varname> can be For better performance, <varname>stats_temp_directory</varname> can be
pointed at a RAM-based file system, decreasing physical I/O requirements. pointed at a RAM-based file system, decreasing physical I/O requirements.
@ -217,13 +217,13 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<para> <para>
Several predefined views, listed in <xref Several predefined views, listed in <xref
linkend="monitoring-stats-dynamic-views-table">, are available to show linkend="monitoring-stats-dynamic-views-table"/>, are available to show
the current state of the system. There are also several other the current state of the system. There are also several other
views, listed in <xref views, listed in <xref
linkend="monitoring-stats-views-table">, available to show the results linkend="monitoring-stats-views-table"/>, available to show the results
of statistics collection. Alternatively, one can of statistics collection. Alternatively, one can
build custom views using the underlying statistics functions, as discussed build custom views using the underlying statistics functions, as discussed
in <xref linkend="monitoring-stats-functions">. in <xref linkend="monitoring-stats-functions"/>.
</para> </para>
<para> <para>
@ -288,7 +288,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry> <entry>
One row per server process, showing information related to One row per server process, showing information related to
the current activity of that process, such as state and current query. the current activity of that process, such as state and current query.
See <xref linkend="pg-stat-activity-view"> for details. See <xref linkend="pg-stat-activity-view"/> for details.
</entry> </entry>
</row> </row>
@ -296,7 +296,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry><structname>pg_stat_replication</structname><indexterm><primary>pg_stat_replication</primary></indexterm></entry> <entry><structname>pg_stat_replication</structname><indexterm><primary>pg_stat_replication</primary></indexterm></entry>
<entry>One row per WAL sender process, showing statistics about <entry>One row per WAL sender process, showing statistics about
replication to that sender's connected standby server. replication to that sender's connected standby server.
See <xref linkend="pg-stat-replication-view"> for details. See <xref linkend="pg-stat-replication-view"/> for details.
</entry> </entry>
</row> </row>
@ -304,7 +304,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry><structname>pg_stat_wal_receiver</structname><indexterm><primary>pg_stat_wal_receiver</primary></indexterm></entry> <entry><structname>pg_stat_wal_receiver</structname><indexterm><primary>pg_stat_wal_receiver</primary></indexterm></entry>
<entry>Only one row, showing statistics about the WAL receiver from <entry>Only one row, showing statistics about the WAL receiver from
that receiver's connected server. that receiver's connected server.
See <xref linkend="pg-stat-wal-receiver-view"> for details. See <xref linkend="pg-stat-wal-receiver-view"/> for details.
</entry> </entry>
</row> </row>
@ -312,7 +312,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry><structname>pg_stat_subscription</structname><indexterm><primary>pg_stat_subscription</primary></indexterm></entry> <entry><structname>pg_stat_subscription</structname><indexterm><primary>pg_stat_subscription</primary></indexterm></entry>
<entry>At least one row per subscription, showing information about <entry>At least one row per subscription, showing information about
the subscription workers. the subscription workers.
See <xref linkend="pg-stat-subscription"> for details. See <xref linkend="pg-stat-subscription"/> for details.
</entry> </entry>
</row> </row>
@ -320,7 +320,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry><structname>pg_stat_ssl</structname><indexterm><primary>pg_stat_ssl</primary></indexterm></entry> <entry><structname>pg_stat_ssl</structname><indexterm><primary>pg_stat_ssl</primary></indexterm></entry>
<entry>One row per connection (regular and replication), showing information about <entry>One row per connection (regular and replication), showing information about
SSL used on this connection. SSL used on this connection.
See <xref linkend="pg-stat-ssl-view"> for details. See <xref linkend="pg-stat-ssl-view"/> for details.
</entry> </entry>
</row> </row>
@ -328,7 +328,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry><structname>pg_stat_progress_vacuum</structname><indexterm><primary>pg_stat_progress_vacuum</primary></indexterm></entry> <entry><structname>pg_stat_progress_vacuum</structname><indexterm><primary>pg_stat_progress_vacuum</primary></indexterm></entry>
<entry>One row for each backend (including autovacuum worker processes) running <entry>One row for each backend (including autovacuum worker processes) running
<command>VACUUM</command>, showing current progress. <command>VACUUM</command>, showing current progress.
See <xref linkend='vacuum-progress-reporting'>. See <xref linkend='vacuum-progress-reporting'/>.
</entry> </entry>
</row> </row>
@ -352,7 +352,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry><structname>pg_stat_archiver</structname><indexterm><primary>pg_stat_archiver</primary></indexterm></entry> <entry><structname>pg_stat_archiver</structname><indexterm><primary>pg_stat_archiver</primary></indexterm></entry>
<entry>One row only, showing statistics about the <entry>One row only, showing statistics about the
WAL archiver process's activity. See WAL archiver process's activity. See
<xref linkend="pg-stat-archiver-view"> for details. <xref linkend="pg-stat-archiver-view"/> for details.
</entry> </entry>
</row> </row>
@ -360,14 +360,14 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry><structname>pg_stat_bgwriter</structname><indexterm><primary>pg_stat_bgwriter</primary></indexterm></entry> <entry><structname>pg_stat_bgwriter</structname><indexterm><primary>pg_stat_bgwriter</primary></indexterm></entry>
<entry>One row only, showing statistics about the <entry>One row only, showing statistics about the
background writer process's activity. See background writer process's activity. See
<xref linkend="pg-stat-bgwriter-view"> for details. <xref linkend="pg-stat-bgwriter-view"/> for details.
</entry> </entry>
</row> </row>
<row> <row>
<entry><structname>pg_stat_database</structname><indexterm><primary>pg_stat_database</primary></indexterm></entry> <entry><structname>pg_stat_database</structname><indexterm><primary>pg_stat_database</primary></indexterm></entry>
<entry>One row per database, showing database-wide statistics. See <entry>One row per database, showing database-wide statistics. See
<xref linkend="pg-stat-database-view"> for details. <xref linkend="pg-stat-database-view"/> for details.
</entry> </entry>
</row> </row>
@ -376,7 +376,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry> <entry>
One row per database, showing database-wide statistics about One row per database, showing database-wide statistics about
query cancels due to conflict with recovery on standby servers. query cancels due to conflict with recovery on standby servers.
See <xref linkend="pg-stat-database-conflicts-view"> for details. See <xref linkend="pg-stat-database-conflicts-view"/> for details.
</entry> </entry>
</row> </row>
@ -385,7 +385,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry> <entry>
One row for each table in the current database, showing statistics One row for each table in the current database, showing statistics
about accesses to that specific table. about accesses to that specific table.
See <xref linkend="pg-stat-all-tables-view"> for details. See <xref linkend="pg-stat-all-tables-view"/> for details.
</entry> </entry>
</row> </row>
@ -427,7 +427,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry> <entry>
One row for each index in the current database, showing statistics One row for each index in the current database, showing statistics
about accesses to that specific index. about accesses to that specific index.
See <xref linkend="pg-stat-all-indexes-view"> for details. See <xref linkend="pg-stat-all-indexes-view"/> for details.
</entry> </entry>
</row> </row>
@ -448,7 +448,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry> <entry>
One row for each table in the current database, showing statistics One row for each table in the current database, showing statistics
about I/O on that specific table. about I/O on that specific table.
See <xref linkend="pg-statio-all-tables-view"> for details. See <xref linkend="pg-statio-all-tables-view"/> for details.
</entry> </entry>
</row> </row>
@ -469,7 +469,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry> <entry>
One row for each index in the current database, One row for each index in the current database,
showing statistics about I/O on that specific index. showing statistics about I/O on that specific index.
See <xref linkend="pg-statio-all-indexes-view"> for details. See <xref linkend="pg-statio-all-indexes-view"/> for details.
</entry> </entry>
</row> </row>
@ -490,7 +490,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry> <entry>
One row for each sequence in the current database, One row for each sequence in the current database,
showing statistics about I/O on that specific sequence. showing statistics about I/O on that specific sequence.
See <xref linkend="pg-statio-all-sequences-view"> for details. See <xref linkend="pg-statio-all-sequences-view"/> for details.
</entry> </entry>
</row> </row>
@ -512,7 +512,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry> <entry>
One row for each tracked function, showing statistics One row for each tracked function, showing statistics
about executions of that function. See about executions of that function. See
<xref linkend="pg-stat-user-functions-view"> for details. <xref linkend="pg-stat-user-functions-view"/> for details.
</entry> </entry>
</row> </row>
@ -609,7 +609,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry>Host name of the connected client, as reported by a <entry>Host name of the connected client, as reported by a
reverse DNS lookup of <structfield>client_addr</structfield>. This field will reverse DNS lookup of <structfield>client_addr</structfield>. This field will
only be non-null for IP connections, and only when <xref only be non-null for IP connections, and only when <xref
linkend="guc-log-hostname"> is enabled. linkend="guc-log-hostname"/> is enabled.
</entry> </entry>
</row> </row>
<row> <row>
@ -731,7 +731,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<entry><structfield>wait_event</structfield></entry> <entry><structfield>wait_event</structfield></entry>
<entry><type>text</type></entry> <entry><type>text</type></entry>
<entry>Wait event name if backend is currently waiting, otherwise NULL. <entry>Wait event name if backend is currently waiting, otherwise NULL.
See <xref linkend="wait-event-table"> for details. See <xref linkend="wait-event-table"/> for details.
</entry> </entry>
</row> </row>
<row> <row>
@ -772,7 +772,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<listitem> <listitem>
<para> <para>
<literal>disabled</literal>: This state is reported if <xref <literal>disabled</literal>: This state is reported if <xref
linkend="guc-track-activities"> is disabled in this backend. linkend="guc-track-activities"/> is disabled in this backend.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -796,7 +796,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
currently executing query. In all other states, it shows the last query currently executing query. In all other states, it shows the last query
that was executed. By default the query text is truncated at 1024 that was executed. By default the query text is truncated at 1024
characters; this value can be changed via the parameter characters; this value can be changed via the parameter
<xref linkend="guc-track-activity-query-size">. <xref linkend="guc-track-activity-query-size"/>.
</entry> </entry>
</row> </row>
<row> <row>
@ -1683,7 +1683,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
<entry>Host name of the connected client, as reported by a <entry>Host name of the connected client, as reported by a
reverse DNS lookup of <structfield>client_addr</structfield>. This field will reverse DNS lookup of <structfield>client_addr</structfield>. This field will
only be non-null for IP connections, and only when <xref only be non-null for IP connections, and only when <xref
linkend="guc-log-hostname"> is enabled. linkend="guc-log-hostname"/> is enabled.
</entry> </entry>
</row> </row>
<row> <row>
@ -1704,7 +1704,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
<entry><structfield>backend_xmin</structfield></entry> <entry><structfield>backend_xmin</structfield></entry>
<entry><type>xid</type></entry> <entry><type>xid</type></entry>
<entry>This standby's <literal>xmin</literal> horizon reported <entry>This standby's <literal>xmin</literal> horizon reported
by <xref linkend="guc-hot-standby-feedback">.</entry> by <xref linkend="guc-hot-standby-feedback"/>.</entry>
</row> </row>
<row> <row>
<entry><structfield>state</structfield></entry> <entry><structfield>state</structfield></entry>
@ -2347,7 +2347,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
<entry><type>bigint</type></entry> <entry><type>bigint</type></entry>
<entry>Number of queries canceled due to conflicts with recovery <entry>Number of queries canceled due to conflicts with recovery
in this database. (Conflicts occur only on standby servers; see in this database. (Conflicts occur only on standby servers; see
<xref linkend="pg-stat-database-conflicts-view"> for details.) <xref linkend="pg-stat-database-conflicts-view"/> for details.)
</entry> </entry>
</row> </row>
<row> <row>
@ -2356,7 +2356,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
<entry>Number of temporary files created by queries in this database. <entry>Number of temporary files created by queries in this database.
All temporary files are counted, regardless of why the temporary file All temporary files are counted, regardless of why the temporary file
was created (e.g., sorting or hashing), and regardless of the was created (e.g., sorting or hashing), and regardless of the
<xref linkend="guc-log-temp-files"> setting. <xref linkend="guc-log-temp-files"/> setting.
</entry> </entry>
</row> </row>
<row> <row>
@ -2365,7 +2365,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
<entry>Total amount of data written to temporary files by queries in <entry>Total amount of data written to temporary files by queries in
this database. All temporary files are counted, regardless of why this database. All temporary files are counted, regardless of why
the temporary file was created, and the temporary file was created, and
regardless of the <xref linkend="guc-log-temp-files"> setting. regardless of the <xref linkend="guc-log-temp-files"/> setting.
</entry> </entry>
</row> </row>
<row> <row>
@ -2942,7 +2942,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
<para> <para>
The <structname>pg_stat_user_functions</structname> view will contain The <structname>pg_stat_user_functions</structname> view will contain
one row for each tracked function, showing statistics about executions of one row for each tracked function, showing statistics about executions of
that function. The <xref linkend="guc-track-functions"> parameter that function. The <xref linkend="guc-track-functions"/> parameter
controls exactly which functions are tracked. controls exactly which functions are tracked.
</para> </para>
@ -2967,7 +2967,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
<para> <para>
Additional functions related to statistics collection are listed in <xref Additional functions related to statistics collection are listed in <xref
linkend="monitoring-stats-funcs-table">. linkend="monitoring-stats-funcs-table"/>.
</para> </para>
<table id="monitoring-stats-funcs-table"> <table id="monitoring-stats-funcs-table">
@ -3074,7 +3074,7 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
Sometimes it may be more convenient to obtain just a subset of this Sometimes it may be more convenient to obtain just a subset of this
information. In such cases, an older set of per-backend statistics information. In such cases, an older set of per-backend statistics
access functions can be used; these are shown in <xref access functions can be used; these are shown in <xref
linkend="monitoring-stats-backend-funcs-table">. linkend="monitoring-stats-backend-funcs-table"/>.
These access functions use a backend ID number, which ranges from one These access functions use a backend ID number, which ranges from one
to the number of currently active backends. to the number of currently active backends.
The function <function>pg_stat_get_backend_idset</function> provides a The function <function>pg_stat_get_backend_idset</function> provides a
@ -3162,7 +3162,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
<entry><literal><function>pg_stat_get_backend_wait_event_type(integer)</function></literal></entry> <entry><literal><function>pg_stat_get_backend_wait_event_type(integer)</function></literal></entry>
<entry><type>text</type></entry> <entry><type>text</type></entry>
<entry>Wait event type name if backend is currently waiting, otherwise NULL. <entry>Wait event type name if backend is currently waiting, otherwise NULL.
See <xref linkend="wait-event-table"> for details. See <xref linkend="wait-event-table"/> for details.
</entry> </entry>
</row> </row>
@ -3170,7 +3170,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
<entry><literal><function>pg_stat_get_backend_wait_event(integer)</function></literal></entry> <entry><literal><function>pg_stat_get_backend_wait_event(integer)</function></literal></entry>
<entry><type>text</type></entry> <entry><type>text</type></entry>
<entry>Wait event name if backend is currently waiting, otherwise NULL. <entry>Wait event name if backend is currently waiting, otherwise NULL.
See <xref linkend="wait-event-table"> for details. See <xref linkend="wait-event-table"/> for details.
</entry> </entry>
</row> </row>
@ -3230,9 +3230,9 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
</itemizedlist> </itemizedlist>
Details of the <structname>pg_locks</structname> view appear in Details of the <structname>pg_locks</structname> view appear in
<xref linkend="view-pg-locks">. <xref linkend="view-pg-locks"/>.
For more information on locking and managing concurrency with For more information on locking and managing concurrency with
<productname>PostgreSQL</productname>, refer to <xref linkend="mvcc">. <productname>PostgreSQL</productname>, refer to <xref linkend="mvcc"/>.
</para> </para>
</sect1> </sect1>
@ -3296,7 +3296,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
<entry><structfield>phase</structfield></entry> <entry><structfield>phase</structfield></entry>
<entry><type>text</type></entry> <entry><type>text</type></entry>
<entry> <entry>
Current processing phase of vacuum. See <xref linkend='vacuum-phases'>. Current processing phase of vacuum. See <xref linkend='vacuum-phases'/>.
</entry> </entry>
</row> </row>
<row> <row>
@ -3343,7 +3343,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
<entry> <entry>
Number of dead tuples that we can store before needing to perform Number of dead tuples that we can store before needing to perform
an index vacuum cycle, based on an index vacuum cycle, based on
<xref linkend="guc-maintenance-work-mem">. <xref linkend="guc-maintenance-work-mem"/>.
</entry> </entry>
</row> </row>
<row> <row>
@ -3390,7 +3390,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
<command>VACUUM</command> is currently vacuuming the indexes. If a table has <command>VACUUM</command> is currently vacuuming the indexes. If a table has
any indexes, this will happen at least once per vacuum, after the heap any indexes, this will happen at least once per vacuum, after the heap
has been completely scanned. It may happen multiple times per vacuum has been completely scanned. It may happen multiple times per vacuum
if <xref linkend="guc-maintenance-work-mem"> is insufficient to if <xref linkend="guc-maintenance-work-mem"/> is insufficient to
store the number of dead tuples found. store the number of dead tuples found.
</entry> </entry>
</row> </row>
@ -3478,7 +3478,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
explicitly tell the configure script to make the probes available explicitly tell the configure script to make the probes available
in <productname>PostgreSQL</productname>. To include DTrace support in <productname>PostgreSQL</productname>. To include DTrace support
specify <option>--enable-dtrace</option> to configure. See <xref specify <option>--enable-dtrace</option> to configure. See <xref
linkend="install-procedure"> for further information. linkend="install-procedure"/> for further information.
</para> </para>
</sect2> </sect2>
@ -3487,8 +3487,8 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
<para> <para>
A number of standard probes are provided in the source code, A number of standard probes are provided in the source code,
as shown in <xref linkend="dtrace-probe-point-table">; as shown in <xref linkend="dtrace-probe-point-table"/>;
<xref linkend="typedefs-table"> <xref linkend="typedefs-table"/>
shows the types used in the probes. More probes can certainly be shows the types used in the probes. More probes can certainly be
added to enhance <productname>PostgreSQL</productname>'s observability. added to enhance <productname>PostgreSQL</productname>'s observability.
</para> </para>
@ -3752,7 +3752,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
<entry><literal>(ForkNumber, BlockNumber, Oid, Oid, Oid)</literal></entry> <entry><literal>(ForkNumber, BlockNumber, Oid, Oid, Oid)</literal></entry>
<entry>Probe that fires when a server process begins to write a dirty <entry>Probe that fires when a server process begins to write a dirty
buffer. (If this happens often, it implies that buffer. (If this happens often, it implies that
<xref linkend="guc-shared-buffers"> is too <xref linkend="guc-shared-buffers"/> is too
small or the background writer control parameters need adjustment.) small or the background writer control parameters need adjustment.)
arg0 and arg1 contain the fork and block numbers of the page. arg0 and arg1 contain the fork and block numbers of the page.
arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
@ -3770,7 +3770,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
<entry>Probe that fires when a server process begins to write a <entry>Probe that fires when a server process begins to write a
dirty WAL buffer because no more WAL buffer space is available. dirty WAL buffer because no more WAL buffer space is available.
(If this happens often, it implies that (If this happens often, it implies that
<xref linkend="guc-wal-buffers"> is too small.)</entry> <xref linkend="guc-wal-buffers"/> is too small.)</entry>
</row> </row>
<row> <row>
<entry><literal>wal-buffer-write-dirty-done</literal></entry> <entry><literal>wal-buffer-write-dirty-done</literal></entry>

66
doc/src/sgml/mvcc.sgml
View File

@ -165,7 +165,7 @@
<primary>transaction isolation level</primary> <primary>transaction isolation level</primary>
</indexterm> </indexterm>
The SQL standard and PostgreSQL-implemented transaction isolation levels The SQL standard and PostgreSQL-implemented transaction isolation levels
are described in <xref linkend="mvcc-isolevel-table">. are described in <xref linkend="mvcc-isolevel-table"/>.
</para> </para>
<table tocentry="1" id="mvcc-isolevel-table"> <table tocentry="1" id="mvcc-isolevel-table">
@ -286,7 +286,7 @@
<para> <para>
To set the transaction isolation level of a transaction, use the To set the transaction isolation level of a transaction, use the
command <xref linkend="sql-set-transaction">. command <xref linkend="sql-set-transaction"/>.
</para> </para>
<important> <important>
@ -296,8 +296,8 @@
made to a sequence (and therefore the counter of a made to a sequence (and therefore the counter of a
column declared using <type>serial</type>) are immediately visible column declared using <type>serial</type>) are immediately visible
to all other transactions and are not rolled back if the transaction to all other transactions and are not rolled back if the transaction
that made the changes aborts. See <xref linkend="functions-sequence"> that made the changes aborts. See <xref linkend="functions-sequence"/>
and <xref linkend="datatype-serial">. and <xref linkend="datatype-serial"/>.
</para> </para>
</important> </important>
@ -461,7 +461,7 @@ COMMIT;
even though they are not yet committed.) This is a stronger even though they are not yet committed.) This is a stronger
guarantee than is required by the <acronym>SQL</acronym> standard guarantee than is required by the <acronym>SQL</acronym> standard
for this isolation level, and prevents all of the phenomena described for this isolation level, and prevents all of the phenomena described
in <xref linkend="mvcc-isolevel-table"> except for serialization in <xref linkend="mvcc-isolevel-table"/> except for serialization
anomalies. As mentioned above, this is anomalies. As mentioned above, this is
specifically allowed by the standard, which only describes the specifically allowed by the standard, which only describes the
<emphasis>minimum</emphasis> protections each isolation level must <emphasis>minimum</emphasis> protections each isolation level must
@ -748,7 +748,7 @@ ERROR: could not serialize access due to read/write dependencies among transact
<para> <para>
Don't leave connections dangling <quote>idle in transaction</quote> Don't leave connections dangling <quote>idle in transaction</quote>
longer than necessary. The configuration parameter longer than necessary. The configuration parameter
<xref linkend="guc-idle-in-transaction-session-timeout"> may be used to <xref linkend="guc-idle-in-transaction-session-timeout"/> may be used to
automatically disconnect lingering sessions. automatically disconnect lingering sessions.
</para> </para>
</listitem> </listitem>
@ -765,9 +765,9 @@ ERROR: could not serialize access due to read/write dependencies among transact
locks into a single relation-level predicate lock because the predicate locks into a single relation-level predicate lock because the predicate
lock table is short of memory, an increase in the rate of serialization lock table is short of memory, an increase in the rate of serialization
failures may occur. You can avoid this by increasing 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-relation"/>, and/or
<xref linkend="guc-max-pred-locks-per-page">. <xref linkend="guc-max-pred-locks-per-page"/>.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -775,8 +775,8 @@ ERROR: could not serialize access due to read/write dependencies among transact
A sequential scan will always necessitate a relation-level predicate A sequential scan will always necessitate a relation-level predicate
lock. This can result in an increased rate of serialization failures. lock. This can result in an increased rate of serialization failures.
It may be helpful to encourage the use of index scans by reducing It may be helpful to encourage the use of index scans by reducing
<xref linkend="guc-random-page-cost"> and/or increasing <xref linkend="guc-random-page-cost"/> and/or increasing
<xref linkend="guc-cpu-tuple-cost">. Be sure to weigh any decrease <xref linkend="guc-cpu-tuple-cost"/>. Be sure to weigh any decrease
in transaction rollbacks and restarts against any overall change in in transaction rollbacks and restarts against any overall change in
query execution time. query execution time.
</para> </para>
@ -811,7 +811,7 @@ ERROR: could not serialize access due to read/write dependencies among transact
server, use the server, use the
<link linkend="view-pg-locks"><structname>pg_locks</structname></link> <link linkend="view-pg-locks"><structname>pg_locks</structname></link>
system view. For more information on monitoring the status of the lock system view. For more information on monitoring the status of the lock
manager subsystem, refer to <xref linkend="monitoring">. manager subsystem, refer to <xref linkend="monitoring"/>.
</para> </para>
<sect2 id="locking-tables"> <sect2 id="locking-tables">
@ -826,14 +826,14 @@ ERROR: could not serialize access due to read/write dependencies among transact
which they are used automatically by which they are used automatically by
<productname>PostgreSQL</productname>. You can also acquire any <productname>PostgreSQL</productname>. You can also acquire any
of these locks explicitly with the command <xref of these locks explicitly with the command <xref
linkend="sql-lock">. linkend="sql-lock"/>.
Remember that all of these lock modes are table-level locks, Remember that all of these lock modes are table-level locks,
even if the name contains the word even if the name contains the word
<quote>row</quote>; the names of the lock modes are historical. <quote>row</quote>; the names of the lock modes are historical.
To some extent the names reflect the typical usage of each lock To some extent the names reflect the typical usage of each lock
mode &mdash; but the semantics are all the same. The only real difference mode &mdash; but the semantics are all the same. The only real difference
between one lock mode and another is the set of lock modes with between one lock mode and another is the set of lock modes with
which each conflicts (see <xref linkend="table-lock-compatibility">). which each conflicts (see <xref linkend="table-lock-compatibility"/>).
Two transactions cannot hold locks of conflicting Two transactions cannot hold locks of conflicting
modes on the same table at the same time. (However, a transaction modes on the same table at the same time. (However, a transaction
never conflicts with itself. For example, it might acquire never conflicts with itself. For example, it might acquire
@ -929,7 +929,7 @@ ERROR: could not serialize access due to read/write dependencies among transact
<command>CREATE STATISTICS</command> and <command>CREATE STATISTICS</command> and
<command>ALTER TABLE VALIDATE</command> and other <command>ALTER TABLE VALIDATE</command> and other
<command>ALTER TABLE</command> variants (for full details see <command>ALTER TABLE</command> variants (for full details see
<xref linkend="sql-altertable">). <xref linkend="sql-altertable"/>).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -972,7 +972,7 @@ ERROR: could not serialize access due to read/write dependencies among transact
<para> <para>
Acquired by <command>CREATE COLLATION</command>, Acquired by <command>CREATE COLLATION</command>,
<command>CREATE TRIGGER</command>, and many forms of <command>CREATE TRIGGER</command>, and many forms of
<command>ALTER TABLE</command> (see <xref linkend="sql-altertable">). <command>ALTER TABLE</command> (see <xref linkend="sql-altertable"/>).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1053,9 +1053,9 @@ ERROR: could not serialize access due to read/write dependencies among transact
<table tocentry="1" id="table-lock-compatibility"> <table tocentry="1" id="table-lock-compatibility">
<title> Conflicting Lock Modes</title> <title> Conflicting Lock Modes</title>
<tgroup cols="9"> <tgroup cols="9">
<colspec colnum="2" colname="lockst"> <colspec colnum="2" colname="lockst"/>
<colspec colnum="9" colname="lockend"> <colspec colnum="9" colname="lockend"/>
<spanspec namest="lockst" nameend="lockend" spanname="lockreq"> <spanspec namest="lockst" nameend="lockend" spanname="lockreq"/>
<thead> <thead>
<row> <row>
<entry morerows="1">Requested Lock Mode</entry> <entry morerows="1">Requested Lock Mode</entry>
@ -1173,7 +1173,7 @@ ERROR: could not serialize access due to read/write dependencies among transact
In addition to table-level locks, there are row-level locks, which In addition to table-level locks, there are row-level locks, which
are listed as below with the contexts in which they are used are listed as below with the contexts in which they are used
automatically by <productname>PostgreSQL</productname>. See automatically by <productname>PostgreSQL</productname>. See
<xref linkend="row-lock-compatibility"> for a complete table of <xref linkend="row-lock-compatibility"/> for a complete table of
row-level lock conflicts. Note that a transaction can hold row-level lock conflicts. Note that a transaction can hold
conflicting locks on the same row, even in different subtransactions; conflicting locks on the same row, even in different subtransactions;
but other than that, two transactions can never hold conflicting locks but other than that, two transactions can never hold conflicting locks
@ -1208,7 +1208,7 @@ ERROR: could not serialize access due to read/write dependencies among transact
<literal>SERIALIZABLE</literal> transaction, <literal>SERIALIZABLE</literal> transaction,
however, an error will be thrown if a row to be locked has changed however, an error will be thrown if a row to be locked has changed
since the transaction started. For further discussion see since the transaction started. For further discussion see
<xref linkend="applevel-consistency">. <xref linkend="applevel-consistency"/>.
</para> </para>
<para> <para>
The <literal>FOR UPDATE</literal> lock mode The <literal>FOR UPDATE</literal> lock mode
@ -1286,9 +1286,9 @@ ERROR: could not serialize access due to read/write dependencies among transact
<table tocentry="1" id="row-lock-compatibility"> <table tocentry="1" id="row-lock-compatibility">
<title>Conflicting Row-level Locks</title> <title>Conflicting Row-level Locks</title>
<tgroup cols="5"> <tgroup cols="5">
<colspec colnum="2" colname="lockst"> <colspec colnum="2" colname="lockst"/>
<colspec colnum="5" colname="lockend"> <colspec colnum="5" colname="lockend"/>
<spanspec namest="lockst" nameend="lockend" spanname="lockreq"> <spanspec namest="lockst" nameend="lockend" spanname="lockreq"/>
<thead> <thead>
<row> <row>
<entry morerows="1">Requested Lock Mode</entry> <entry morerows="1">Requested Lock Mode</entry>
@ -1495,8 +1495,8 @@ UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 22222;
<para> <para>
Both advisory locks and regular locks are stored in a shared memory Both advisory locks and regular locks are stored in a shared memory
pool whose size is defined by the configuration variables pool whose size is defined by the configuration variables
<xref linkend="guc-max-locks-per-transaction"> and <xref linkend="guc-max-locks-per-transaction"/> and
<xref linkend="guc-max-connections">. <xref linkend="guc-max-connections"/>.
Care must be taken not to exhaust this Care must be taken not to exhaust this
memory or the server will be unable to grant any locks at all. memory or the server will be unable to grant any locks at all.
This imposes an upper limit on the number of advisory locks This imposes an upper limit on the number of advisory locks
@ -1529,7 +1529,7 @@ SELECT pg_advisory_lock(q.id) FROM
<para> <para>
The functions provided to manipulate advisory locks are described in The functions provided to manipulate advisory locks are described in
<xref linkend="functions-advisory-locks">. <xref linkend="functions-advisory-locks"/>.
</para> </para>
</sect2> </sect2>
@ -1565,7 +1565,7 @@ SELECT pg_advisory_lock(q.id) FROM
</para> </para>
<para> <para>
As mentioned in <xref linkend="xact-serializable">, Serializable As mentioned in <xref linkend="xact-serializable"/>, Serializable
transactions are just Repeatable Read transactions which add transactions are just Repeatable Read transactions which add
nonblocking monitoring for dangerous patterns of read/write conflicts. nonblocking monitoring for dangerous patterns of read/write conflicts.
When a pattern is detected which could cause a cycle in the apparent When a pattern is detected which could cause a cycle in the apparent
@ -1598,13 +1598,13 @@ SELECT pg_advisory_lock(q.id) FROM
</para> </para>
<para> <para>
See <xref linkend="xact-serializable"> for performance suggestions. See <xref linkend="xact-serializable"/> for performance suggestions.
</para> </para>
<warning> <warning>
<para> <para>
This level of integrity protection using Serializable transactions This level of integrity protection using Serializable transactions
does not yet extend to hot standby mode (<xref linkend="hot-standby">). does not yet extend to hot standby mode (<xref linkend="hot-standby"/>).
Because of that, those using hot standby may want to use Repeatable Because of that, those using hot standby may want to use Repeatable
Read and explicit locking on the master. Read and explicit locking on the master.
</para> </para>
@ -1687,8 +1687,8 @@ SELECT pg_advisory_lock(q.id) FROM
<title>Caveats</title> <title>Caveats</title>
<para> <para>
Some DDL commands, currently only <xref linkend="sql-truncate"> and the Some DDL commands, currently only <xref linkend="sql-truncate"/> and the
table-rewriting forms of <xref linkend="sql-altertable">, are not table-rewriting forms of <xref linkend="sql-altertable"/>, are not
MVCC-safe. This means that after the truncation or rewrite commits, the MVCC-safe. This means that after the truncation or rewrite commits, the
table will appear empty to concurrent transactions, if they are using a table will appear empty to concurrent transactions, if they are using a
snapshot taken before the DDL command committed. This will only be an snapshot taken before the DDL command committed. This will only be an
@ -1705,7 +1705,7 @@ SELECT pg_advisory_lock(q.id) FROM
<para> <para>
Support for the Serializable transaction isolation level has not yet Support for the Serializable transaction isolation level has not yet
been added to Hot Standby replication targets (described in been added to Hot Standby replication targets (described in
<xref linkend="hot-standby">). The strictest isolation level currently <xref linkend="hot-standby"/>). The strictest isolation level currently
supported in hot standby mode is Repeatable Read. While performing all supported in hot standby mode is Repeatable Read. While performing all
permanent database writes within Serializable transactions on the permanent database writes within Serializable transactions on the
master will ensure that all standbys will eventually reach a consistent master will ensure that all standbys will eventually reach a consistent

2
doc/src/sgml/nls.sgml
View File

@ -272,7 +272,7 @@ msgstr "Die Datei %2$s hat %1$u Zeichen."
open file %s</literal>) should probably not start with a open file %s</literal>) should probably not start with a
capital letter (if your language distinguishes letter case) or capital letter (if your language distinguishes letter case) or
end with a period (if your language uses punctuation marks). end with a period (if your language uses punctuation marks).
It might help to read <xref linkend="error-style-guide">. It might help to read <xref linkend="error-style-guide"/>.
</para> </para>
</listitem> </listitem>

2
doc/src/sgml/oid2name.sgml
View File

@ -30,7 +30,7 @@
<application>oid2name</application> is a utility program that helps administrators to <application>oid2name</application> is a utility program that helps administrators to
examine the file structure used by PostgreSQL. To make use of it, you need examine the file structure used by PostgreSQL. To make use of it, you need
to be familiar with the database file structure, which is described in to be familiar with the database file structure, which is described in
<xref linkend="storage">. <xref linkend="storage"/>.
</para> </para>
<note> <note>

34
doc/src/sgml/parallel.sgml
View File

@ -64,10 +64,10 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
worker processes</link> equal to the number worker processes</link> equal to the number
of workers chosen by the planner. The number of background workers that of workers chosen by the planner. The number of background workers that
the planner will consider using is limited to at most the planner will consider using is limited to at most
<xref linkend="guc-max-parallel-workers-per-gather">. The total number <xref linkend="guc-max-parallel-workers-per-gather"/>. The total number
of background workers that can exist at any one time is limited by both 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-worker-processes"/> and
<xref linkend="guc-max-parallel-workers">. Therefore, it is possible for a <xref linkend="guc-max-parallel-workers"/>. Therefore, it is possible for a
parallel query to run with fewer workers than planned, or even with 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 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 that are available, so this can result in poor query performance. If this
@ -118,7 +118,7 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
<xref linkend="guc-max-parallel-workers-per-gather"> must be set to a <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 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 general principle that no more workers should be used than the number
configured via <varname>max_parallel_workers_per_gather</varname>. configured via <varname>max_parallel_workers_per_gather</varname>.
@ -127,7 +127,7 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
<listitem> <listitem>
<para> <para>
<xref linkend="guc-dynamic-shared-memory-type"> must be set to a <xref linkend="guc-dynamic-shared-memory-type"/> must be set to a
value other than <literal>none</literal>. Parallel query requires dynamic value other than <literal>none</literal>. Parallel query requires dynamic
shared memory in order to pass data between cooperating processes. shared memory in order to pass data between cooperating processes.
</para> </para>
@ -178,7 +178,7 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
Most system-defined functions are <literal>PARALLEL SAFE</literal>, Most system-defined functions are <literal>PARALLEL SAFE</literal>,
but user-defined functions are marked <literal>PARALLEL but user-defined functions are marked <literal>PARALLEL
UNSAFE</literal> by default. See the discussion of UNSAFE</literal> by default. See the discussion of
<xref linkend="parallel-safety">. <xref linkend="parallel-safety"/>.
</para> </para>
</listitem> </listitem>
@ -215,7 +215,7 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
<para> <para>
No background workers can be obtained because of the limitation that No background workers can be obtained because of the limitation that
the total number of background workers cannot exceed the total number of background workers cannot exceed
<xref linkend="guc-max-worker-processes">. <xref linkend="guc-max-worker-processes"/>.
</para> </para>
</listitem> </listitem>
@ -223,7 +223,7 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
<para> <para>
No background workers can be obtained because of the limitation that No background workers can be obtained because of the limitation that
the total number of background workers launched for purposes of the total number of background workers launched for purposes of
parallel query cannot exceed <xref linkend="guc-max-parallel-workers">. parallel query cannot exceed <xref linkend="guc-max-parallel-workers"/>.
</para> </para>
</listitem> </listitem>
@ -236,7 +236,7 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
send such a message, this can only occur when using a client that send such a message, this can only occur when using a client that
does not rely on libpq. If this is a frequent does not rely on libpq. If this is a frequent
occurrence, it may be a good idea to set occurrence, it may be a good idea to set
<xref linkend="guc-max-parallel-workers-per-gather"> to zero in <xref linkend="guc-max-parallel-workers-per-gather"/> to zero in
sessions where it is likely, so as to avoid generating query plans sessions where it is likely, so as to avoid generating query plans
that may be suboptimal when run serially. that may be suboptimal when run serially.
</para> </para>
@ -374,7 +374,7 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
must be <link linkend="parallel-safety">safe</link> for parallelism and must must be <link linkend="parallel-safety">safe</link> for parallelism and must
have a combine function. If the aggregate has a transition state of type have a combine function. If the aggregate has a transition state of type
<literal>internal</literal>, it must have serialization and deserialization <literal>internal</literal>, it must have serialization and deserialization
functions. See <xref linkend="sql-createaggregate"> for more details. functions. See <xref linkend="sql-createaggregate"/> for more details.
Parallel aggregation is not supported if any aggregate function call Parallel aggregation is not supported if any aggregate function call
contains <literal>DISTINCT</literal> or <literal>ORDER BY</literal> clause and is also contains <literal>DISTINCT</literal> or <literal>ORDER BY</literal> clause and is also
not supported for ordered set aggregates or when the query involves not supported for ordered set aggregates or when the query involves
@ -389,15 +389,15 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
<para> <para>
If a query that is expected to do so does not produce a parallel plan, 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 you can try reducing <xref linkend="guc-parallel-setup-cost"/> or
<xref linkend="guc-parallel-tuple-cost">. Of course, this plan may turn <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 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 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 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 them both to zero), there may be some reason why the query planner is
unable to generate a parallel plan for your query. See unable to generate a parallel plan for your query. See
<xref linkend="when-can-parallel-query-be-used"> and <xref linkend="when-can-parallel-query-be-used"/> and
<xref linkend="parallel-safety"> for information on why this may be <xref linkend="parallel-safety"/> for information on why this may be
the case. the case.
</para> </para>
@ -473,11 +473,11 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
where it conceivably be done, we do not try, since this would be expensive 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 and error-prone. Instead, all user-defined functions are assumed to
be parallel unsafe unless otherwise marked. When using be parallel unsafe unless otherwise marked. When using
<xref linkend="sql-createfunction"> or <xref linkend="sql-createfunction"/> or
<xref linkend="sql-alterfunction">, markings can be set by specifying <xref linkend="sql-alterfunction"/>, markings can be set by specifying
<literal>PARALLEL SAFE</literal>, <literal>PARALLEL RESTRICTED</literal>, or <literal>PARALLEL SAFE</literal>, <literal>PARALLEL RESTRICTED</literal>, or
<literal>PARALLEL UNSAFE</literal> as appropriate. When using <literal>PARALLEL UNSAFE</literal> as appropriate. When using
<xref linkend="sql-createaggregate">, the <xref linkend="sql-createaggregate"/>, the
<literal>PARALLEL</literal> option can be specified with <literal>SAFE</literal>, <literal>PARALLEL</literal> option can be specified with <literal>SAFE</literal>,
<literal>RESTRICTED</literal>, or <literal>UNSAFE</literal> as the corresponding value. <literal>RESTRICTED</literal>, or <literal>UNSAFE</literal> as the corresponding value.
</para> </para>

8
doc/src/sgml/passwordcheck.sgml
View File

@ -10,15 +10,15 @@
<para> <para>
The <filename>passwordcheck</filename> module checks users' passwords The <filename>passwordcheck</filename> module checks users' passwords
whenever they are set with whenever they are set with
<xref linkend="sql-createrole"> or <xref linkend="sql-createrole"/> or
<xref linkend="sql-alterrole">. <xref linkend="sql-alterrole"/>.
If a password is considered too weak, it will be rejected and If a password is considered too weak, it will be rejected and
the command will terminate with an error. the command will terminate with an error.
</para> </para>
<para> <para>
To enable this module, add <literal>'$libdir/passwordcheck'</literal> To enable this module, add <literal>'$libdir/passwordcheck'</literal>
to <xref linkend="guc-shared-preload-libraries"> in to <xref linkend="guc-shared-preload-libraries"/> in
<filename>postgresql.conf</filename>, then restart the server. <filename>postgresql.conf</filename>, then restart the server.
</para> </para>
@ -49,7 +49,7 @@
For this reason, <filename>passwordcheck</filename> is not For this reason, <filename>passwordcheck</filename> is not
recommended if your security requirements are high. recommended if your security requirements are high.
It is more secure to use an external authentication method such as GSSAPI It is more secure to use an external authentication method such as GSSAPI
(see <xref linkend="client-authentication">) than to rely on (see <xref linkend="client-authentication"/>) than to rely on
passwords within the database. passwords within the database.
</para> </para>
<para> <para>

68
doc/src/sgml/perform.sgml
View File

@ -31,7 +31,7 @@
plan to match the query structure and the properties of the data plan to match the query structure and the properties of the data
is absolutely critical for good performance, so the system includes is absolutely critical for good performance, so the system includes
a complex <firstterm>planner</firstterm> that tries to choose good plans. a complex <firstterm>planner</firstterm> that tries to choose good plans.
You can use the <xref linkend="sql-explain"> command You can use the <xref linkend="sql-explain"/> command
to see what query plan the planner creates for any query. to see what query plan the planner creates for any query.
Plan-reading is an art that requires some experience to master, Plan-reading is an art that requires some experience to master,
but this section attempts to cover the basics. but this section attempts to cover the basics.
@ -132,9 +132,9 @@ EXPLAIN SELECT * FROM tenk1;
<para> <para>
The costs are measured in arbitrary units determined by the planner's The costs are measured in arbitrary units determined by the planner's
cost parameters (see <xref linkend="runtime-config-query-constants">). cost parameters (see <xref linkend="runtime-config-query-constants"/>).
Traditional practice is to measure the costs in units of disk page Traditional practice is to measure the costs in units of disk page
fetches; that is, <xref linkend="guc-seq-page-cost"> is conventionally fetches; that is, <xref linkend="guc-seq-page-cost"/> is conventionally
set to <literal>1.0</literal> and the other cost parameters are set relative set to <literal>1.0</literal> and the other cost parameters are set relative
to that. The examples in this section are run with the default cost to that. The examples in this section are run with the default cost
parameters. parameters.
@ -182,8 +182,8 @@ SELECT relpages, reltuples FROM pg_class WHERE relname = 'tenk1';
you will find that <classname>tenk1</classname> has 358 disk you will find that <classname>tenk1</classname> has 358 disk
pages and 10000 rows. The estimated cost is computed as (disk pages read * pages and 10000 rows. The estimated cost is computed as (disk pages read *
<xref linkend="guc-seq-page-cost">) + (rows scanned * <xref linkend="guc-seq-page-cost"/>) + (rows scanned *
<xref linkend="guc-cpu-tuple-cost">). By default, <xref linkend="guc-cpu-tuple-cost"/>). By default,
<varname>seq_page_cost</varname> is 1.0 and <varname>cpu_tuple_cost</varname> is 0.01, <varname>seq_page_cost</varname> is 1.0 and <varname>cpu_tuple_cost</varname> is 0.01,
so the estimated cost is (358 * 1.0) + (10000 * 0.01) = 458. so the estimated cost is (358 * 1.0) + (10000 * 0.01) = 458.
</para> </para>
@ -209,7 +209,7 @@ EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 7000;
<literal>WHERE</literal> clause. <literal>WHERE</literal> clause.
However, the scan will still have to visit all 10000 rows, so the cost However, the scan will still have to visit all 10000 rows, so the cost
hasn't decreased; in fact it has gone up a bit (by 10000 * <xref hasn't decreased; in fact it has gone up a bit (by 10000 * <xref
linkend="guc-cpu-operator-cost">, to be exact) to reflect the extra CPU linkend="guc-cpu-operator-cost"/>, to be exact) to reflect the extra CPU
time spent checking the <literal>WHERE</literal> condition. time spent checking the <literal>WHERE</literal> condition.
</para> </para>
@ -508,9 +508,9 @@ WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2;
<para> <para>
One way to look at variant plans is to force the planner to disregard One way to look at variant plans is to force the planner to disregard
whatever strategy it thought was the cheapest, using the enable/disable whatever strategy it thought was the cheapest, using the enable/disable
flags described in <xref linkend="runtime-config-query-enable">. flags described in <xref linkend="runtime-config-query-enable"/>.
(This is a crude tool, but useful. See (This is a crude tool, but useful. See
also <xref linkend="explicit-joins">.) also <xref linkend="explicit-joins"/>.)
For example, if we're unconvinced that sequential-scan-and-sort is the best way to For example, if we're unconvinced that sequential-scan-and-sort is the best way to
deal with table <literal>onek</literal> in the previous example, we could try deal with table <literal>onek</literal> in the previous example, we could try
@ -828,7 +828,7 @@ EXPLAIN UPDATE parent SET f2 = f2 + 1 WHERE f1 = 101;
Second, the measurement overhead added by <command>EXPLAIN Second, the measurement overhead added by <command>EXPLAIN
ANALYZE</command> can be significant, especially on machines with slow ANALYZE</command> can be significant, especially on machines with slow
<function>gettimeofday()</function> operating-system calls. You can use the <function>gettimeofday()</function> operating-system calls. You can use the
<xref linkend="pgtesttiming"> tool to measure the overhead of timing <xref linkend="pgtesttiming"/> tool to measure the overhead of timing
on your system. on your system.
</para> </para>
@ -1032,7 +1032,7 @@ WHERE tablename = 'road';
arrays for each column, can be set on a arrays for each column, can be set on a
column-by-column basis using the <command>ALTER TABLE SET STATISTICS</command> column-by-column basis using the <command>ALTER TABLE SET STATISTICS</command>
command, or globally by setting the command, or globally by setting the
<xref linkend="guc-default-statistics-target"> configuration variable. <xref linkend="guc-default-statistics-target"/> configuration variable.
The default limit is presently 100 entries. Raising the limit The default limit is presently 100 entries. Raising the limit
might allow more accurate planner estimates to be made, particularly for might allow more accurate planner estimates to be made, particularly for
columns with irregular data distributions, at the price of consuming columns with irregular data distributions, at the price of consuming
@ -1043,7 +1043,7 @@ WHERE tablename = 'road';
<para> <para>
Further details about the planner's use of statistics can be found in Further details about the planner's use of statistics can be found in
<xref linkend="planner-stats-details">. <xref linkend="planner-stats-details"/>.
</para> </para>
</sect2> </sect2>
@ -1087,7 +1087,7 @@ WHERE tablename = 'road';
<para> <para>
Statistics objects are created using Statistics objects are created using
<xref linkend="sql-createstatistics">, which see for more details. <xref linkend="sql-createstatistics"/>, which see for more details.
Creation of such an object merely creates a catalog entry expressing Creation of such an object merely creates a catalog entry expressing
interest in the statistics. Actual data collection is performed interest in the statistics. Actual data collection is performed
by <command>ANALYZE</command> (either a manual command, or background by <command>ANALYZE</command> (either a manual command, or background
@ -1323,7 +1323,7 @@ SELECT * FROM a, b, c WHERE a.id = b.id AND b.ref = c.id;
<productname>PostgreSQL</productname> planner will switch from exhaustive <productname>PostgreSQL</productname> planner will switch from exhaustive
search to a <firstterm>genetic</firstterm> probabilistic search search to a <firstterm>genetic</firstterm> probabilistic search
through a limited number of possibilities. (The switch-over threshold is through a limited number of possibilities. (The switch-over threshold is
set by the <xref linkend="guc-geqo-threshold"> run-time set by the <xref linkend="guc-geqo-threshold"/> run-time
parameter.) parameter.)
The genetic search takes less time, but it won't The genetic search takes less time, but it won't
necessarily find the best possible plan. necessarily find the best possible plan.
@ -1379,7 +1379,7 @@ SELECT * FROM a JOIN (b JOIN c ON (b.ref = c.id)) ON (a.id = b.id);
<para> <para>
To force the planner to follow the join order laid out by explicit To force the planner to follow the join order laid out by explicit
<literal>JOIN</literal>s, <literal>JOIN</literal>s,
set the <xref linkend="guc-join-collapse-limit"> run-time parameter to 1. set the <xref linkend="guc-join-collapse-limit"/> run-time parameter to 1.
(Other possible values are discussed below.) (Other possible values are discussed below.)
</para> </para>
@ -1436,8 +1436,8 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
</para> </para>
<para> <para>
<xref linkend="guc-from-collapse-limit"> and <xref <xref linkend="guc-from-collapse-limit"/> and <xref
linkend="guc-join-collapse-limit"> linkend="guc-join-collapse-limit"/>
are similarly named because they do almost the same thing: one controls are similarly named because they do almost the same thing: one controls
when the planner will <quote>flatten out</quote> subqueries, and the when the planner will <quote>flatten out</quote> subqueries, and the
other controls when it will flatten out explicit joins. Typically other controls when it will flatten out explicit joins. Typically
@ -1488,7 +1488,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
<title>Use <command>COPY</command></title> <title>Use <command>COPY</command></title>
<para> <para>
Use <xref linkend="sql-copy"> to load Use <xref linkend="sql-copy"/> to load
all the rows in one command, instead of using a series of all the rows in one command, instead of using a series of
<command>INSERT</command> commands. The <command>COPY</command> <command>INSERT</command> commands. The <command>COPY</command>
command is optimized for loading large numbers of rows; it is less command is optimized for loading large numbers of rows; it is less
@ -1500,7 +1500,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
<para> <para>
If you cannot use <command>COPY</command>, it might help to use <xref If you cannot use <command>COPY</command>, it might help to use <xref
linkend="sql-prepare"> to create a linkend="sql-prepare"/> to create a
prepared <command>INSERT</command> statement, and then use prepared <command>INSERT</command> statement, and then use
<command>EXECUTE</command> as many times as required. This avoids <command>EXECUTE</command> as many times as required. This avoids
some of the overhead of repeatedly parsing and planning some of the overhead of repeatedly parsing and planning
@ -1523,7 +1523,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
needs to be written, because in case of an error, the files needs to be written, because in case of an error, the files
containing the newly loaded data will be removed anyway. containing the newly loaded data will be removed anyway.
However, this consideration only applies when However, this consideration only applies when
<xref linkend="guc-wal-level"> is <literal>minimal</literal> as all commands <xref linkend="guc-wal-level"/> is <literal>minimal</literal> as all commands
must write WAL otherwise. must write WAL otherwise.
</para> </para>
@ -1581,7 +1581,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
<title>Increase <varname>maintenance_work_mem</varname></title> <title>Increase <varname>maintenance_work_mem</varname></title>
<para> <para>
Temporarily increasing the <xref linkend="guc-maintenance-work-mem"> Temporarily increasing the <xref linkend="guc-maintenance-work-mem"/>
configuration variable when loading large amounts of data can configuration variable when loading large amounts of data can
lead to improved performance. This will help to speed up <command>CREATE lead to improved performance. This will help to speed up <command>CREATE
INDEX</command> commands and <command>ALTER TABLE ADD FOREIGN KEY</command> commands. INDEX</command> commands and <command>ALTER TABLE ADD FOREIGN KEY</command> commands.
@ -1594,7 +1594,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
<title>Increase <varname>max_wal_size</varname></title> <title>Increase <varname>max_wal_size</varname></title>
<para> <para>
Temporarily increasing the <xref linkend="guc-max-wal-size"> Temporarily increasing the <xref linkend="guc-max-wal-size"/>
configuration variable can also configuration variable can also
make large data loads faster. This is because loading a large make large data loads faster. This is because loading a large
amount of data into <productname>PostgreSQL</productname> will amount of data into <productname>PostgreSQL</productname> will
@ -1617,9 +1617,9 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
new base backup after the load has completed than to process a large new base backup after the load has completed than to process a large
amount of incremental WAL data. To prevent incremental WAL logging amount of incremental WAL data. To prevent incremental WAL logging
while loading, disable archiving and streaming replication, by setting while loading, disable archiving and streaming replication, by setting
<xref linkend="guc-wal-level"> to <literal>minimal</literal>, <xref linkend="guc-wal-level"/> to <literal>minimal</literal>,
<xref linkend="guc-archive-mode"> to <literal>off</literal>, and <xref linkend="guc-archive-mode"/> to <literal>off</literal>, and
<xref linkend="guc-max-wal-senders"> to zero. <xref linkend="guc-max-wal-senders"/> to zero.
But note that changing these settings requires a server restart. But note that changing these settings requires a server restart.
</para> </para>
@ -1668,7 +1668,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
<para> <para>
Whenever you have significantly altered the distribution of data Whenever you have significantly altered the distribution of data
within a table, running <xref linkend="sql-analyze"> is strongly recommended. This within a table, running <xref linkend="sql-analyze"/> is strongly recommended. This
includes bulk loading large amounts of data into the table. Running includes bulk loading large amounts of data into the table. Running
<command>ANALYZE</command> (or <command>VACUUM ANALYZE</command>) <command>ANALYZE</command> (or <command>VACUUM ANALYZE</command>)
ensures that the planner has up-to-date statistics about the ensures that the planner has up-to-date statistics about the
@ -1677,8 +1677,8 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
performance on any tables with inaccurate or nonexistent performance on any tables with inaccurate or nonexistent
statistics. Note that if the autovacuum daemon is enabled, it might statistics. Note that if the autovacuum daemon is enabled, it might
run <command>ANALYZE</command> automatically; see run <command>ANALYZE</command> automatically; see
<xref linkend="vacuum-for-statistics"> <xref linkend="vacuum-for-statistics"/>
and <xref linkend="autovacuum"> for more information. and <xref linkend="autovacuum"/> for more information.
</para> </para>
</sect2> </sect2>
@ -1779,8 +1779,8 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
<varname>maintenance_work_mem</varname>; rather, you'd do that while <varname>maintenance_work_mem</varname>; rather, you'd do that while
manually recreating indexes and foreign keys afterwards. manually recreating indexes and foreign keys afterwards.
And don't forget to <command>ANALYZE</command> when you're done; see And don't forget to <command>ANALYZE</command> when you're done; see
<xref linkend="vacuum-for-statistics"> <xref linkend="vacuum-for-statistics"/>
and <xref linkend="autovacuum"> for more information. and <xref linkend="autovacuum"/> for more information.
</para> </para>
</sect2> </sect2>
</sect1> </sect1>
@ -1816,14 +1816,14 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
<listitem> <listitem>
<para> <para>
Turn off <xref linkend="guc-fsync">; there is no need to flush Turn off <xref linkend="guc-fsync"/>; there is no need to flush
data to disk. data to disk.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Turn off <xref linkend="guc-synchronous-commit">; there might be no Turn off <xref linkend="guc-synchronous-commit"/>; there might be no
need to force <acronym>WAL</acronym> writes to disk on every need to force <acronym>WAL</acronym> writes to disk on every
commit. This setting does risk transaction loss (though not data commit. This setting does risk transaction loss (though not data
corruption) in case of a crash of the <emphasis>database</emphasis>. corruption) in case of a crash of the <emphasis>database</emphasis>.
@ -1832,15 +1832,15 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
<listitem> <listitem>
<para> <para>
Turn off <xref linkend="guc-full-page-writes">; there is no need Turn off <xref linkend="guc-full-page-writes"/>; there is no need
to guard against partial page writes. to guard against partial page writes.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Increase <xref linkend="guc-max-wal-size"> and <xref Increase <xref linkend="guc-max-wal-size"/> and <xref
linkend="guc-checkpoint-timeout">; this reduces the frequency linkend="guc-checkpoint-timeout"/>; this reduces the frequency
of checkpoints, but increases the storage requirements of of checkpoints, but increases the storage requirements of
<filename>/pg_wal</filename>. <filename>/pg_wal</filename>.
</para> </para>

2
doc/src/sgml/pgbuffercache.sgml
View File

@ -33,7 +33,7 @@
<title>The <structname>pg_buffercache</structname> View</title> <title>The <structname>pg_buffercache</structname> View</title>
<para> <para>
The definitions of the columns exposed by the view are shown in <xref linkend="pgbuffercache-columns">. The definitions of the columns exposed by the view are shown in <xref linkend="pgbuffercache-columns"/>.
</para> </para>
<table id="pgbuffercache-columns"> <table id="pgbuffercache-columns">

8
doc/src/sgml/pgcrypto.sgml
View File

@ -40,7 +40,7 @@ digest(data bytea, type text) returns bytea
<literal>sha384</literal> and <literal>sha512</literal>. <literal>sha384</literal> and <literal>sha512</literal>.
If <filename>pgcrypto</filename> was built with If <filename>pgcrypto</filename> was built with
OpenSSL, more algorithms are available, as detailed in OpenSSL, more algorithms are available, as detailed in
<xref linkend="pgcrypto-with-without-openssl">. <xref linkend="pgcrypto-with-without-openssl"/>.
</para> </para>
<para> <para>
@ -129,7 +129,7 @@ hmac(data bytea, key text, type text) returns bytea
</orderedlist> </orderedlist>
<para> <para>
<xref linkend="pgcrypto-crypt-algorithms"> lists the algorithms <xref linkend="pgcrypto-crypt-algorithms"/> lists the algorithms
supported by the <function>crypt()</function> function. supported by the <function>crypt()</function> function.
</para> </para>
@ -247,7 +247,7 @@ gen_salt(type text [, iter_count integer ]) returns text
&mdash; which is somewhat impractical. If the <parameter>iter_count</parameter> &mdash; which is somewhat impractical. If the <parameter>iter_count</parameter>
parameter is omitted, the default iteration count is used. parameter is omitted, the default iteration count is used.
Allowed values for <parameter>iter_count</parameter> depend on the algorithm and Allowed values for <parameter>iter_count</parameter> depend on the algorithm and
are shown in <xref linkend="pgcrypto-icfc-table">. are shown in <xref linkend="pgcrypto-icfc-table"/>.
</para> </para>
<table id="pgcrypto-icfc-table"> <table id="pgcrypto-icfc-table">
@ -292,7 +292,7 @@ gen_salt(type text [, iter_count integer ]) returns text
</para> </para>
<para> <para>
<xref linkend="pgcrypto-hash-speed-table"> gives an overview of the relative slowness <xref linkend="pgcrypto-hash-speed-table"/> gives an overview of the relative slowness
of different hashing algorithms. of different hashing algorithms.
The table shows how much time it would take to try all The table shows how much time it would take to try all
combinations of characters in an 8-character password, assuming combinations of characters in an 8-character password, assuming

2
doc/src/sgml/pgprewarm.sgml
View File

@ -13,7 +13,7 @@
or the <productname>PostgreSQL</productname> buffer cache. Prewarming or the <productname>PostgreSQL</productname> buffer cache. Prewarming
can be performed manually using the <filename>pg_prewarm</filename> function, can be performed manually using the <filename>pg_prewarm</filename> function,
or can be performed automatically by including <literal>pg_prewarm</literal> in or can be performed automatically by including <literal>pg_prewarm</literal> in
<xref linkend="guc-shared-preload-libraries">. In the latter case, the <xref linkend="guc-shared-preload-libraries"/>. In the latter case, the
system will run a background worker which periodically records the contents system will run a background worker which periodically records the contents
of shared buffers in a file called <filename>autoprewarm.blocks</filename> and of shared buffers in a file called <filename>autoprewarm.blocks</filename> and
will, using 2 background workers, reload those same blocks after a restart. will, using 2 background workers, reload those same blocks after a restart.

2
doc/src/sgml/pgrowlocks.sgml
View File

@ -33,7 +33,7 @@ pgrowlocks(text) returns setof record
<para> <para>
The parameter is the name of a table. The result is a set of records, The parameter is the name of a table. The result is a set of records,
with one row for each locked row within the table. The output columns with one row for each locked row within the table. The output columns
are shown in <xref linkend="pgrowlocks-columns">. are shown in <xref linkend="pgrowlocks-columns"/>.
</para> </para>
<table id="pgrowlocks-columns"> <table id="pgrowlocks-columns">

8
doc/src/sgml/pgstandby.sgml
View File

@ -41,7 +41,7 @@
<varname>restore_command</varname>, which is needed to turn a standard <varname>restore_command</varname>, which is needed to turn a standard
archive recovery into a warm standby operation. Other archive recovery into a warm standby operation. Other
configuration is required as well, all of which is described in the main configuration is required as well, all of which is described in the main
server manual (see <xref linkend="warm-standby">). server manual (see <xref linkend="warm-standby"/>).
</para> </para>
<para> <para>
@ -180,7 +180,7 @@ restore_command = 'pg_standby <replaceable>archiveDir</replaceable> %f %p %r'
Set the number of seconds (up to 60, default 5) to sleep between Set the number of seconds (up to 60, default 5) to sleep between
tests to see if the WAL file to be restored is available in tests to see if the WAL file to be restored is available in
the archive yet. The default setting is not necessarily the archive yet. The default setting is not necessarily
recommended; consult <xref linkend="warm-standby"> for discussion. recommended; consult <xref linkend="warm-standby"/> for discussion.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -216,7 +216,7 @@ restore_command = 'pg_standby <replaceable>archiveDir</replaceable> %f %p %r'
after which a fast failover will be performed. after which a fast failover will be performed.
A setting of zero (the default) means wait forever. A setting of zero (the default) means wait forever.
The default setting is not necessarily recommended; The default setting is not necessarily recommended;
consult <xref linkend="warm-standby"> for discussion. consult <xref linkend="warm-standby"/> for discussion.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -388,7 +388,7 @@ recovery_end_command = 'del C:\pgsql.trigger.5442'
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="pgarchivecleanup"></member> <member><xref linkend="pgarchivecleanup"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>

8
doc/src/sgml/pgstatstatements.sgml
View File

@ -14,7 +14,7 @@
<para> <para>
The module must be loaded by adding <literal>pg_stat_statements</literal> to The module must be loaded by adding <literal>pg_stat_statements</literal> to
<xref linkend="guc-shared-preload-libraries"> in <xref linkend="guc-shared-preload-libraries"/> in
<filename>postgresql.conf</filename>, because it requires additional shared memory. <filename>postgresql.conf</filename>, because it requires additional shared memory.
This means that a server restart is needed to add or remove the module. This means that a server restart is needed to add or remove the module.
</para> </para>
@ -38,7 +38,7 @@
contains one row for each distinct database ID, user ID and query contains one row for each distinct database ID, user ID and query
ID (up to the maximum number of distinct statements that the module ID (up to the maximum number of distinct statements that the module
can track). The columns of the view are shown in can track). The columns of the view are shown in
<xref linkend="pgstatstatements-columns">. <xref linkend="pgstatstatements-columns"/>.
</para> </para>
<table id="pgstatstatements-columns"> <table id="pgstatstatements-columns">
@ -207,7 +207,7 @@
<entry></entry> <entry></entry>
<entry> <entry>
Total time the statement spent reading blocks, in milliseconds Total time the statement spent reading blocks, in milliseconds
(if <xref linkend="guc-track-io-timing"> is enabled, otherwise zero) (if <xref linkend="guc-track-io-timing"/> is enabled, otherwise zero)
</entry> </entry>
</row> </row>
@ -217,7 +217,7 @@
<entry></entry> <entry></entry>
<entry> <entry>
Total time the statement spent writing blocks, in milliseconds Total time the statement spent writing blocks, in milliseconds
(if <xref linkend="guc-track-io-timing"> is enabled, otherwise zero) (if <xref linkend="guc-track-io-timing"/> is enabled, otherwise zero)
</entry> </entry>
</row> </row>

4
doc/src/sgml/pgstattuple.sgml
View File

@ -55,7 +55,7 @@ dead_tuple_percent | 0.69
free_space | 8932 free_space | 8932
free_percent | 1.95 free_percent | 1.95
</programlisting> </programlisting>
The output columns are described in <xref linkend="pgstattuple-columns">. The output columns are described in <xref linkend="pgstattuple-columns"/>.
</para> </para>
<table id="pgstattuple-columns"> <table id="pgstattuple-columns">
@ -509,7 +509,7 @@ dead_tuple_percent | 0
approx_free_space | 11996 approx_free_space | 11996
approx_free_percent | 2.09 approx_free_percent | 2.09
</programlisting> </programlisting>
The output columns are described in <xref linkend="pgstatapprox-columns">. The output columns are described in <xref linkend="pgstatapprox-columns"/>.
</para> </para>
<para> <para>

4
doc/src/sgml/pgtrgm.sgml
View File

@ -58,8 +58,8 @@
<para> <para>
The functions provided by the <filename>pg_trgm</filename> module The functions provided by the <filename>pg_trgm</filename> module
are shown in <xref linkend="pgtrgm-func-table">, the operators are shown in <xref linkend="pgtrgm-func-table"/>, the operators
in <xref linkend="pgtrgm-op-table">. in <xref linkend="pgtrgm-op-table"/>.
</para> </para>
<table id="pgtrgm-func-table"> <table id="pgtrgm-func-table">

6
doc/src/sgml/planstats.sgml
View File

@ -5,7 +5,7 @@
<para> <para>
This chapter builds on the material covered in <xref This chapter builds on the material covered in <xref
linkend="using-explain"> and <xref linkend="planner-stats"> to show some linkend="using-explain"/> and <xref linkend="planner-stats"/> to show some
additional details about how the planner uses the additional details about how the planner uses the
system statistics to estimate the number of rows each part of a query might system statistics to estimate the number of rows each part of a query might
return. This is a significant part of the planning process, return. This is a significant part of the planning process,
@ -49,7 +49,7 @@ EXPLAIN SELECT * FROM tenk1;
</programlisting> </programlisting>
How the planner determines the cardinality of <structname>tenk1</structname> How the planner determines the cardinality of <structname>tenk1</structname>
is covered in <xref linkend="planner-stats">, but is repeated here for is covered in <xref linkend="planner-stats"/>, but is repeated here for
completeness. The number of pages and rows is looked up in completeness. The number of pages and rows is looked up in
<structname>pg_class</structname>: <structname>pg_class</structname>:
@ -468,7 +468,7 @@ INSERT INTO t SELECT i % 100, i % 100 FROM generate_series(1, 10000) s(i);
ANALYZE t; ANALYZE t;
</programlisting> </programlisting>
As explained in <xref linkend="planner-stats">, the planner can determine As explained in <xref linkend="planner-stats"/>, the planner can determine
cardinality of <structname>t</structname> using the number of pages and cardinality of <structname>t</structname> using the number of pages and
rows obtained from <structname>pg_class</structname>: rows obtained from <structname>pg_class</structname>:

14
doc/src/sgml/plhandler.sgml
View File

@ -29,7 +29,7 @@
special pseudo-type 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. prevents it from being called directly in SQL commands.
For more details on C language calling conventions and dynamic loading, For more details on C language calling conventions and dynamic loading,
see <xref linkend="xfunc-c">. see <xref linkend="xfunc-c"/>.
</para> </para>
<para> <para>
@ -144,7 +144,7 @@ plsample_call_handler(PG_FUNCTION_ARGS)
<para> <para>
After having compiled the handler function into a loadable module After having compiled the handler function into a loadable module
(see <xref linkend="dfunc">), the following commands then (see <xref linkend="dfunc"/>), the following commands then
register the sample procedural language: register the sample procedural language:
<programlisting> <programlisting>
CREATE FUNCTION plsample_call_handler() RETURNS language_handler CREATE FUNCTION plsample_call_handler() RETURNS language_handler
@ -162,9 +162,9 @@ CREATE LANGUAGE plsample
are a <firstterm>validator</firstterm> and an are a <firstterm>validator</firstterm> and an
<firstterm>inline handler</firstterm>. A validator can be provided <firstterm>inline handler</firstterm>. A validator can be provided
to allow language-specific checking to be done during to allow language-specific checking to be done during
<xref linkend="sql-createfunction">. <xref linkend="sql-createfunction"/>.
An inline handler can be provided to allow the language to support An inline handler can be provided to allow the language to support
anonymous code blocks executed via the <xref linkend="sql-do"> command. anonymous code blocks executed via the <xref linkend="sql-do"/> command.
</para> </para>
<para> <para>
@ -191,7 +191,7 @@ CREATE LANGUAGE plsample
<para> <para>
Validator functions should typically honor the <xref Validator functions should typically honor the <xref
linkend="guc-check-function-bodies"> parameter: if it is turned off then linkend="guc-check-function-bodies"/> parameter: if it is turned off then
any expensive or context-sensitive checking should be skipped. If the any expensive or context-sensitive checking should be skipped. If the
language provides for code execution at compilation time, the validator language provides for code execution at compilation time, the validator
must suppress checks that would induce such execution. In particular, must suppress checks that would induce such execution. In particular,
@ -230,7 +230,7 @@ CREATE LANGUAGE plsample
as well as the <command>CREATE LANGUAGE</command> command itself, into as well as the <command>CREATE LANGUAGE</command> command itself, into
an <firstterm>extension</firstterm> so that a simple <command>CREATE EXTENSION</command> an <firstterm>extension</firstterm> so that a simple <command>CREATE EXTENSION</command>
command is sufficient to install the language. See command is sufficient to install the language. See
<xref linkend="extend-extensions"> for information about writing <xref linkend="extend-extensions"/> for information about writing
extensions. extensions.
</para> </para>
@ -238,7 +238,7 @@ CREATE LANGUAGE plsample
The procedural languages included in the standard distribution The procedural languages included in the standard distribution
are good references when trying to write your own language handler. are good references when trying to write your own language handler.
Look into the <filename>src/pl</filename> subdirectory of the source tree. Look into the <filename>src/pl</filename> subdirectory of the source tree.
The <xref linkend="sql-createlanguage"> The <xref linkend="sql-createlanguage"/>
reference page also has some useful details. reference page also has some useful details.
</para> </para>

22
doc/src/sgml/plperl.sgml
View File

@ -41,7 +41,7 @@
<para> <para>
Users of source packages must specially enable the build of Users of source packages must specially enable the build of
PL/Perl during the installation process. (Refer to <xref PL/Perl during the installation process. (Refer to <xref
linkend="installation"> for more information.) Users of linkend="installation"/> for more information.) Users of
binary packages might find PL/Perl in a separate subpackage. binary packages might find PL/Perl in a separate subpackage.
</para> </para>
</note> </note>
@ -51,7 +51,7 @@
<para> <para>
To create a function in the PL/Perl language, use the standard To create a function in the PL/Perl language, use the standard
<xref linkend="sql-createfunction"> <xref linkend="sql-createfunction"/>
syntax: syntax:
<programlisting> <programlisting>
@ -69,7 +69,7 @@ $$ LANGUAGE plperl;
<para> <para>
PL/Perl also supports anonymous code blocks called with the PL/Perl also supports anonymous code blocks called with the
<xref linkend="sql-do"> statement: <xref linkend="sql-do"/> statement:
<programlisting> <programlisting>
DO $$ DO $$
@ -99,11 +99,11 @@ $$ LANGUAGE plperl;
The syntax of the <command>CREATE FUNCTION</command> command requires The syntax of the <command>CREATE FUNCTION</command> command requires
the function body to be written as a string constant. It is usually the function body to be written as a string constant. It is usually
most convenient to use dollar quoting (see <xref most convenient to use dollar quoting (see <xref
linkend="sql-syntax-dollar-quoting">) for the string constant. linkend="sql-syntax-dollar-quoting"/>) for the string constant.
If you choose to use escape string syntax <literal>E''</literal>, If you choose to use escape string syntax <literal>E''</literal>,
you must double any single quote marks (<literal>'</literal>) and backslashes you must double any single quote marks (<literal>'</literal>) and backslashes
(<literal>\</literal>) used in the body of the function (<literal>\</literal>) used in the body of the function
(see <xref linkend="sql-syntax-strings">). (see <xref linkend="sql-syntax-strings"/>).
</para> </para>
<para> <para>
@ -686,9 +686,9 @@ SELECT release_hosts_query();
priority levels. priority levels.
Whether messages of a particular priority are reported to the client, Whether messages of a particular priority are reported to the client,
written to the server log, or both is controlled by the written to the server log, or both is controlled by the
<xref linkend="guc-log-min-messages"> and <xref linkend="guc-log-min-messages"/> and
<xref linkend="guc-client-min-messages"> configuration <xref linkend="guc-client-min-messages"/> configuration
variables. See <xref linkend="runtime-config"> for more variables. See <xref linkend="runtime-config"/> for more
information. information.
</para> </para>
</listitem> </listitem>
@ -792,7 +792,7 @@ SELECT release_hosts_query();
<listitem> <listitem>
<para> <para>
Returns the contents of the referenced array as a string in array literal format Returns the contents of the referenced array as a string in array literal format
(see <xref linkend="arrays-input">). (see <xref linkend="arrays-input"/>).
Returns the argument value unaltered if it's not a reference to an array. Returns the argument value unaltered if it's not a reference to an array.
The delimiter used between elements of the array literal defaults to "<literal>, </literal>" The delimiter used between elements of the array literal defaults to "<literal>, </literal>"
if a delimiter is not specified or is undef. if a delimiter is not specified or is undef.
@ -828,7 +828,7 @@ SELECT release_hosts_query();
<listitem> <listitem>
<para> <para>
Returns the contents of the referenced array as a string in array constructor format Returns the contents of the referenced array as a string in array constructor format
(see <xref linkend="sql-syntax-array-constructors">). (see <xref linkend="sql-syntax-array-constructors"/>).
Individual values are quoted using <function>quote_nullable</function>. Individual values are quoted using <function>quote_nullable</function>.
Returns the argument value, quoted using <function>quote_nullable</function>, Returns the argument value, quoted using <function>quote_nullable</function>,
if it's not a reference to an array. if it's not a reference to an array.
@ -1336,7 +1336,7 @@ DO 'elog(WARNING, join ", ", sort keys %INC)' LANGUAGE plperl;
</para> </para>
<para> <para>
Initialization will happen in the postmaster if the <literal>plperl</literal> library is Initialization will happen in the postmaster if the <literal>plperl</literal> library is
included in <xref linkend="guc-shared-preload-libraries">, in which included in <xref linkend="guc-shared-preload-libraries"/>, in which
case extra consideration should be given to the risk of destabilizing case extra consideration should be given to the risk of destabilizing
the postmaster. The principal reason for making use of this feature the postmaster. The principal reason for making use of this feature
is that Perl modules loaded by <literal>plperl.on_init</literal> need be is that Perl modules loaded by <literal>plperl.on_init</literal> need be

166
doc/src/sgml/plpgsql.sgml
View File

@ -125,14 +125,14 @@
It is also possible to declare a <application>PL/pgSQL</application> It is also possible to declare a <application>PL/pgSQL</application>
function as returning <type>record</type>, which means that the result function as returning <type>record</type>, which means that the result
is a row type whose columns are determined by specification in the is a row type whose columns are determined by specification in the
calling query, as discussed in <xref linkend="queries-tablefunctions">. calling query, as discussed in <xref linkend="queries-tablefunctions"/>.
</para> </para>
<para> <para>
<application>PL/pgSQL</application> functions can be declared to accept a variable <application>PL/pgSQL</application> functions can be declared to accept a variable
number of arguments by using the <literal>VARIADIC</literal> marker. This number of arguments by using the <literal>VARIADIC</literal> marker. This
works exactly the same way as for SQL functions, as discussed in works exactly the same way as for SQL functions, as discussed in
<xref linkend="xfunc-sql-variadic-functions">. <xref linkend="xfunc-sql-variadic-functions"/>.
</para> </para>
<para> <para>
@ -141,8 +141,8 @@
<type>anyelement</type>, <type>anyarray</type>, <type>anynonarray</type>, <type>anyelement</type>, <type>anyarray</type>, <type>anynonarray</type>,
<type>anyenum</type>, and <type>anyrange</type>. The actual <type>anyenum</type>, and <type>anyrange</type>. The actual
data types handled by a polymorphic function can vary from call to data types handled by a polymorphic function can vary from call to
call, as discussed in <xref linkend="extend-types-polymorphic">. call, as discussed in <xref linkend="extend-types-polymorphic"/>.
An example is shown in <xref linkend="plpgsql-declaration-parameters">. An example is shown in <xref linkend="plpgsql-declaration-parameters"/>.
</para> </para>
<para> <para>
@ -170,8 +170,8 @@
<para> <para>
Specific examples appear in Specific examples appear in
<xref linkend="plpgsql-declaration-parameters"> and <xref linkend="plpgsql-declaration-parameters"/> and
<xref linkend="plpgsql-statements-returning">. <xref linkend="plpgsql-statements-returning"/>.
</para> </para>
</sect2> </sect2>
</sect1> </sect1>
@ -181,7 +181,7 @@
<para> <para>
Functions written in <application>PL/pgSQL</application> are defined Functions written in <application>PL/pgSQL</application> are defined
to the server by executing <xref linkend="sql-createfunction"> commands. to the server by executing <xref linkend="sql-createfunction"/> commands.
Such a command would normally look like, say, Such a command would normally look like, say,
<programlisting> <programlisting>
CREATE FUNCTION somefunc(integer, text) RETURNS integer CREATE FUNCTION somefunc(integer, text) RETURNS integer
@ -190,7 +190,7 @@ LANGUAGE plpgsql;
</programlisting> </programlisting>
The function body is simply a string literal so far as <command>CREATE The function body is simply a string literal so far as <command>CREATE
FUNCTION</command> is concerned. It is often helpful to use dollar quoting FUNCTION</command> is concerned. It is often helpful to use dollar quoting
(see <xref linkend="sql-syntax-dollar-quoting">) to write the function (see <xref linkend="sql-syntax-dollar-quoting"/>) to write the function
body, rather than the normal single quote syntax. Without dollar quoting, body, rather than the normal single quote syntax. Without dollar quoting,
any single quotes or backslashes in the function body must be escaped by any single quotes or backslashes in the function body must be escaped by
doubling them. Almost all the examples in this chapter use dollar-quoted doubling them. Almost all the examples in this chapter use dollar-quoted
@ -289,7 +289,7 @@ $$ LANGUAGE plpgsql;
of any <application>PL/pgSQL</application> function. This block provides the of any <application>PL/pgSQL</application> function. This block provides the
declarations of the function's parameters (if any), as well as some declarations of the function's parameters (if any), as well as some
special variables such as <literal>FOUND</literal> (see special variables such as <literal>FOUND</literal> (see
<xref linkend="plpgsql-statements-diagnostics">). The outer block is <xref linkend="plpgsql-statements-diagnostics"/>). The outer block is
labeled with the function's name, meaning that parameters and special labeled with the function's name, meaning that parameters and special
variables can be qualified with the function's name. variables can be qualified with the function's name.
</para> </para>
@ -308,7 +308,7 @@ $$ LANGUAGE plpgsql;
However, a block containing an <literal>EXCEPTION</literal> clause effectively However, a block containing an <literal>EXCEPTION</literal> clause effectively
forms a subtransaction that can be rolled back without affecting the forms a subtransaction that can be rolled back without affecting the
outer transaction. For more about that see <xref outer transaction. For more about that see <xref
linkend="plpgsql-error-trapping">. linkend="plpgsql-error-trapping"/>.
</para> </para>
</sect1> </sect1>
@ -356,7 +356,7 @@ arow RECORD;
assigned to after initialization, so that its value will remain constant assigned to after initialization, so that its value will remain constant
for the duration of the block. for the duration of the block.
The <literal>COLLATE</literal> option specifies a collation to use for the The <literal>COLLATE</literal> option specifies a collation to use for the
variable (see <xref linkend="plpgsql-declaration-collation">). variable (see <xref linkend="plpgsql-declaration-collation"/>).
If <literal>NOT NULL</literal> If <literal>NOT NULL</literal>
is specified, an assignment of a null value results in a run-time is specified, an assignment of a null value results in a run-time
error. All variables declared as <literal>NOT NULL</literal> error. All variables declared as <literal>NOT NULL</literal>
@ -491,7 +491,7 @@ END;
$$ LANGUAGE plpgsql; $$ LANGUAGE plpgsql;
</programlisting> </programlisting>
As discussed in <xref linkend="xfunc-output-parameters">, this As discussed in <xref linkend="xfunc-output-parameters"/>, this
effectively creates an anonymous record type for the function's effectively creates an anonymous record type for the function's
results. If a <literal>RETURNS</literal> clause is given, it must say results. If a <literal>RETURNS</literal> clause is given, it must say
<literal>RETURNS record</literal>. <literal>RETURNS record</literal>.
@ -523,9 +523,9 @@ $$ LANGUAGE plpgsql;
or <type>anyrange</type>), a special parameter <literal>$0</literal> or <type>anyrange</type>), a special parameter <literal>$0</literal>
is created. Its data type is the actual return type of the function, is created. Its data type is the actual return type of the function,
as deduced from the actual input types (see <xref as deduced from the actual input types (see <xref
linkend="extend-types-polymorphic">). linkend="extend-types-polymorphic"/>).
This allows the function to access its actual return type This allows the function to access its actual return type
as shown in <xref linkend="plpgsql-declaration-type">. as shown in <xref linkend="plpgsql-declaration-type"/>.
<literal>$0</literal> is initialized to null and can be modified by <literal>$0</literal> is initialized to null and can be modified by
the function, so it can be used to hold the return value if desired, the function, so it can be used to hold the return value if desired,
though that is not required. <literal>$0</literal> can also be though that is not required. <literal>$0</literal> can also be
@ -740,7 +740,7 @@ SELECT merge_fields(t.*) FROM table1 t WHERE ... ;
When a <application>PL/pgSQL</application> function has one or more When a <application>PL/pgSQL</application> function has one or more
parameters of collatable data types, a collation is identified for each parameters of collatable data types, a collation is identified for each
function call depending on the collations assigned to the actual function call depending on the collations assigned to the actual
arguments, as described in <xref linkend="collation">. If a collation is arguments, as described in <xref linkend="collation"/>. If a collation is
successfully identified (i.e., there are no conflicts of implicit successfully identified (i.e., there are no conflicts of implicit
collations among the arguments) then all the collatable parameters are collations among the arguments) then all the collatable parameters are
treated as having that collation implicitly. This will affect the treated as having that collation implicitly. This will affect the
@ -841,7 +841,7 @@ SELECT <replaceable>expression</replaceable>
to the main SQL engine. While forming the <command>SELECT</command> command, to the main SQL engine. While forming the <command>SELECT</command> command,
any occurrences of <application>PL/pgSQL</application> variable names any occurrences of <application>PL/pgSQL</application> variable names
are replaced by parameters, as discussed in detail in are replaced by parameters, as discussed in detail in
<xref linkend="plpgsql-var-subst">. <xref linkend="plpgsql-var-subst"/>.
This allows the query plan for the <command>SELECT</command> to This allows the query plan for the <command>SELECT</command> to
be prepared just once and then reused for subsequent be prepared just once and then reused for subsequent
evaluations with different values of the variables. Thus, what evaluations with different values of the variables. Thus, what
@ -861,7 +861,7 @@ PREPARE <replaceable>statement_name</replaceable>(integer, integer) AS SELECT $1
parameter values. Normally these details are parameter values. Normally these details are
not important to a <application>PL/pgSQL</application> user, but not important to a <application>PL/pgSQL</application> user, but
they are useful to know when trying to diagnose a problem. they are useful to know when trying to diagnose a problem.
More information appears in <xref linkend="plpgsql-plan-caching">. More information appears in <xref linkend="plpgsql-plan-caching"/>.
</para> </para>
</sect1> </sect1>
@ -874,8 +874,8 @@ PREPARE <replaceable>statement_name</replaceable>(integer, integer) AS SELECT $1
<application>PL/pgSQL</application>. <application>PL/pgSQL</application>.
Anything not recognized as one of these statement types is presumed Anything not recognized as one of these statement types is presumed
to be an SQL command and is sent to the main database engine to execute, to be an SQL command and is sent to the main database engine to execute,
as described in <xref linkend="plpgsql-statements-sql-noresult"> as described in <xref linkend="plpgsql-statements-sql-noresult"/>
and <xref linkend="plpgsql-statements-sql-onerow">. and <xref linkend="plpgsql-statements-sql-onerow"/>.
</para> </para>
<sect2 id="plpgsql-statements-assignment"> <sect2 id="plpgsql-statements-assignment">
@ -900,7 +900,7 @@ PREPARE <replaceable>statement_name</replaceable>(integer, integer) AS SELECT $1
<para> <para>
If the expression's result data type doesn't match the variable's If the expression's result data type doesn't match the variable's
data type, the value will be coerced as though by an assignment cast data type, the value will be coerced as though by an assignment cast
(see <xref linkend="typeconv-query">). If no assignment cast is known (see <xref linkend="typeconv-query"/>). If no assignment cast is known
for the pair of data types involved, the <application>PL/pgSQL</application> for the pair of data types involved, the <application>PL/pgSQL</application>
interpreter will attempt to convert the result value textually, that is interpreter will attempt to convert the result value textually, that is
by applying the result type's output function followed by the variable by applying the result type's output function followed by the variable
@ -933,14 +933,14 @@ my_record.user_id := 20;
in the command text is treated as a parameter, and then the in the command text is treated as a parameter, and then the
current value of the variable is provided as the parameter value current value of the variable is provided as the parameter value
at run time. This is exactly like the processing described earlier at run time. This is exactly like the processing described earlier
for expressions; for details see <xref linkend="plpgsql-var-subst">. for expressions; for details see <xref linkend="plpgsql-var-subst"/>.
</para> </para>
<para> <para>
When executing a SQL command in this way, When executing a SQL command in this way,
<application>PL/pgSQL</application> may cache and re-use the execution <application>PL/pgSQL</application> may cache and re-use the execution
plan for the command, as discussed in plan for the command, as discussed in
<xref linkend="plpgsql-plan-caching">. <xref linkend="plpgsql-plan-caching"/>.
</para> </para>
<para> <para>
@ -966,7 +966,7 @@ PERFORM <replaceable>query</replaceable>;
and the plan is cached in the same way. Also, the special variable and the plan is cached in the same way. Also, the special variable
<literal>FOUND</literal> is set to true if the query produced at <literal>FOUND</literal> is set to true if the query produced at
least one row, or false if it produced no rows (see least one row, or false if it produced no rows (see
<xref linkend="plpgsql-statements-diagnostics">). <xref linkend="plpgsql-statements-diagnostics"/>).
</para> </para>
<note> <note>
@ -1067,7 +1067,7 @@ DELETE ... RETURNING <replaceable>expressions</replaceable> INTO <optional>STRIC
well-defined unless you've used <literal>ORDER BY</literal>.) Any result rows well-defined unless you've used <literal>ORDER BY</literal>.) Any result rows
after the first row are discarded. after the first row are discarded.
You can check the special <literal>FOUND</literal> variable (see You can check the special <literal>FOUND</literal> variable (see
<xref linkend="plpgsql-statements-diagnostics">) to <xref linkend="plpgsql-statements-diagnostics"/>) to
determine whether a row was returned: determine whether a row was returned:
<programlisting> <programlisting>
@ -1147,7 +1147,7 @@ CONTEXT: PL/pgSQL function get_userid(text) line 6 at SQL statement
<para> <para>
To handle cases where you need to process multiple result rows To handle cases where you need to process multiple result rows
from a SQL query, see <xref linkend="plpgsql-records-iterating">. from a SQL query, see <xref linkend="plpgsql-records-iterating"/>.
</para> </para>
</sect2> </sect2>
@ -1161,7 +1161,7 @@ CONTEXT: PL/pgSQL function get_userid(text) line 6 at SQL statement
that will involve different tables or different data types each that will involve different tables or different data types each
time they are executed. <application>PL/pgSQL</application>'s time they are executed. <application>PL/pgSQL</application>'s
normal attempts to cache plans for commands (as discussed in normal attempts to cache plans for commands (as discussed in
<xref linkend="plpgsql-plan-caching">) will not work in such <xref linkend="plpgsql-plan-caching"/>) will not work in such
scenarios. To handle this sort of problem, the scenarios. To handle this sort of problem, the
<command>EXECUTE</command> statement is provided: <command>EXECUTE</command> statement is provided:
@ -1283,7 +1283,7 @@ EXECUTE format('SELECT count(*) FROM %I '
<para> <para>
The <application>PL/pgSQL</application> The <application>PL/pgSQL</application>
<command>EXECUTE</command> statement is not related to the <command>EXECUTE</command> statement is not related to the
<xref linkend="sql-execute"> SQL <xref linkend="sql-execute"/> SQL
statement supported by the statement supported by the
<productname>PostgreSQL</productname> server. The server's <productname>PostgreSQL</productname> server. The server's
<command>EXECUTE</command> statement cannot be used directly within <command>EXECUTE</command> statement cannot be used directly within
@ -1319,7 +1319,7 @@ EXECUTE format('SELECT count(*) FROM %I '
of single quotes. The recommended method for quoting fixed text in your of single quotes. The recommended method for quoting fixed text in your
function body is dollar quoting. (If you have legacy code that does function body is dollar quoting. (If you have legacy code that does
not use dollar quoting, please refer to the not use dollar quoting, please refer to the
overview in <xref linkend="plpgsql-quote-tips">, which can save you overview in <xref linkend="plpgsql-quote-tips"/>, which can save you
some effort when translating said code to a more reasonable scheme.) some effort when translating said code to a more reasonable scheme.)
</para> </para>
@ -1347,7 +1347,7 @@ EXECUTE 'UPDATE tbl SET '
This example demonstrates the use of the This example demonstrates the use of the
<function>quote_ident</function> and <function>quote_ident</function> and
<function>quote_literal</function> functions (see <xref <function>quote_literal</function> functions (see <xref
linkend="functions-string">). For safety, expressions containing column linkend="functions-string"/>). For safety, expressions containing column
or table identifiers should be passed through or table identifiers should be passed through
<function>quote_ident</function> before insertion in a dynamic query. <function>quote_ident</function> before insertion in a dynamic query.
Expressions containing values that should be literal strings in the Expressions containing values that should be literal strings in the
@ -1394,7 +1394,7 @@ EXECUTE 'UPDATE tbl SET '
</programlisting> </programlisting>
(At present, <literal>IS NOT DISTINCT FROM</literal> is handled much less (At present, <literal>IS NOT DISTINCT FROM</literal> is handled much less
efficiently than <literal>=</literal>, so don't do this unless you must. efficiently than <literal>=</literal>, so don't do this unless you must.
See <xref linkend="functions-comparison"> for See <xref linkend="functions-comparison"/> for
more information on nulls and <literal>IS DISTINCT</literal>.) more information on nulls and <literal>IS DISTINCT</literal>.)
</para> </para>
@ -1420,7 +1420,7 @@ EXECUTE 'UPDATE tbl SET '
<para> <para>
Dynamic SQL statements can also be safely constructed using the Dynamic SQL statements can also be safely constructed using the
<function>format</function> function (see <xref <function>format</function> function (see <xref
linkend="functions-string">). For example: linkend="functions-string"/>). For example:
<programlisting> <programlisting>
EXECUTE format('UPDATE tbl SET %I = %L ' EXECUTE format('UPDATE tbl SET %I = %L '
'WHERE key = %L', colname, newvalue, keyvalue); 'WHERE key = %L', colname, newvalue, keyvalue);
@ -1442,7 +1442,7 @@ EXECUTE format('UPDATE tbl SET %I = $1 WHERE key = $2', colname)
<para> <para>
A much larger example of a dynamic command and A much larger example of a dynamic command and
<command>EXECUTE</command> can be seen in <xref <command>EXECUTE</command> can be seen in <xref
linkend="plpgsql-porting-ex2">, which builds and executes a linkend="plpgsql-porting-ex2"/>, which builds and executes a
<command>CREATE FUNCTION</command> command to define a new function. <command>CREATE FUNCTION</command> command to define a new function.
</para> </para>
</sect2> </sect2>
@ -1461,12 +1461,12 @@ GET <optional> CURRENT </optional> DIAGNOSTICS <replaceable>variable</replaceabl
This command allows retrieval of system status indicators. This command allows retrieval of system status indicators.
<literal>CURRENT</literal> is a noise word (but see also <command>GET STACKED <literal>CURRENT</literal> is a noise word (but see also <command>GET STACKED
DIAGNOSTICS</command> in <xref linkend="plpgsql-exception-diagnostics">). DIAGNOSTICS</command> in <xref linkend="plpgsql-exception-diagnostics"/>).
Each <replaceable>item</replaceable> is a key word identifying a status Each <replaceable>item</replaceable> is a key word identifying a status
value to be assigned to the specified <replaceable>variable</replaceable> value to be assigned to the specified <replaceable>variable</replaceable>
(which should be of the right data type to receive it). The currently (which should be of the right data type to receive it). The currently
available status items are shown available status items are shown
in <xref linkend="plpgsql-current-diagnostics-values">. Colon-equal in <xref linkend="plpgsql-current-diagnostics-values"/>. Colon-equal
(<literal>:=</literal>) can be used instead of the SQL-standard <literal>=</literal> (<literal>:=</literal>) can be used instead of the SQL-standard <literal>=</literal>
token. An example: token. An example:
<programlisting> <programlisting>
@ -1503,7 +1503,7 @@ GET DIAGNOSTICS integer_var = ROW_COUNT;
<entry><literal>PG_CONTEXT</literal></entry> <entry><literal>PG_CONTEXT</literal></entry>
<entry><type>text</type></entry> <entry><type>text</type></entry>
<entry>line(s) of text describing the current call stack <entry>line(s) of text describing the current call stack
(see <xref linkend="plpgsql-call-stack">)</entry> (see <xref linkend="plpgsql-call-stack"/>)</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
@ -1856,7 +1856,7 @@ SELECT * FROM get_available_flightid(CURRENT_DATE);
allow users to define set-returning functions allow users to define set-returning functions
that do not have this limitation. Currently, the point at that do not have this limitation. Currently, the point at
which data begins being written to disk is controlled by the which data begins being written to disk is controlled by the
<xref linkend="guc-work-mem"> <xref linkend="guc-work-mem"/>
configuration variable. Administrators who have sufficient configuration variable. Administrators who have sufficient
memory to store larger result sets in memory should consider memory to store larger result sets in memory should consider
increasing this parameter. increasing this parameter.
@ -2440,8 +2440,8 @@ $$ LANGUAGE plpgsql;
<para> <para>
<application>PL/pgSQL</application> variables are substituted into the query text, <application>PL/pgSQL</application> variables are substituted into the query text,
and the query plan is cached for possible re-use, as discussed in and the query plan is cached for possible re-use, as discussed in
detail in <xref linkend="plpgsql-var-subst"> and detail in <xref linkend="plpgsql-var-subst"/> and
<xref linkend="plpgsql-plan-caching">. <xref linkend="plpgsql-plan-caching"/>.
</para> </para>
<para> <para>
@ -2465,7 +2465,7 @@ END LOOP <optional> <replaceable>label</replaceable> </optional>;
<para> <para>
Another way to specify the query whose results should be iterated Another way to specify the query whose results should be iterated
through is to declare it as a cursor. This is described in through is to declare it as a cursor. This is described in
<xref linkend="plpgsql-cursor-for-loop">. <xref linkend="plpgsql-cursor-for-loop"/>.
</para> </para>
</sect2> </sect2>
@ -2605,7 +2605,7 @@ END;
<para> <para>
The <replaceable>condition</replaceable> names can be any of The <replaceable>condition</replaceable> names can be any of
those shown in <xref linkend="errcodes-appendix">. A category those shown in <xref linkend="errcodes-appendix"/>. A category
name matches any error within its category. The special name matches any error within its category. The special
condition name <literal>OTHERS</literal> matches every error type except condition name <literal>OTHERS</literal> matches every error type except
<literal>QUERY_CANCELED</literal> and <literal>ASSERT_FAILURE</literal>. <literal>QUERY_CANCELED</literal> and <literal>ASSERT_FAILURE</literal>.
@ -2729,7 +2729,7 @@ SELECT merge_db(1, 'dennis');
<para> <para>
Within an exception handler, the special variable Within an exception handler, the special variable
<varname>SQLSTATE</varname> contains the error code that corresponds to <varname>SQLSTATE</varname> contains the error code that corresponds to
the exception that was raised (refer to <xref linkend="errcodes-table"> the exception that was raised (refer to <xref linkend="errcodes-table"/>
for a list of possible error codes). The special variable for a list of possible error codes). The special variable
<varname>SQLERRM</varname> contains the error message associated with the <varname>SQLERRM</varname> contains the error message associated with the
exception. These variables are undefined outside exception handlers. exception. These variables are undefined outside exception handlers.
@ -2748,7 +2748,7 @@ GET STACKED DIAGNOSTICS <replaceable>variable</replaceable> { = | := } <replacea
value to be assigned to the specified <replaceable>variable</replaceable> value to be assigned to the specified <replaceable>variable</replaceable>
(which should be of the right data type to receive it). The currently (which should be of the right data type to receive it). The currently
available status items are shown available status items are shown
in <xref linkend="plpgsql-exception-diagnostics-values">. in <xref linkend="plpgsql-exception-diagnostics-values"/>.
</para> </para>
<table id="plpgsql-exception-diagnostics-values"> <table id="plpgsql-exception-diagnostics-values">
@ -2811,7 +2811,7 @@ GET STACKED DIAGNOSTICS <replaceable>variable</replaceable> { = | := } <replacea
<entry><literal>PG_EXCEPTION_CONTEXT</literal></entry> <entry><literal>PG_EXCEPTION_CONTEXT</literal></entry>
<entry><type>text</type></entry> <entry><type>text</type></entry>
<entry>line(s) of text describing the call stack at the time of the <entry>line(s) of text describing the call stack at the time of the
exception (see <xref linkend="plpgsql-call-stack">)</entry> exception (see <xref linkend="plpgsql-call-stack"/>)</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
@ -2847,7 +2847,7 @@ END;
<para> <para>
The <command>GET DIAGNOSTICS</command> command, previously described The <command>GET DIAGNOSTICS</command> command, previously described
in <xref linkend="plpgsql-statements-diagnostics">, retrieves information in <xref linkend="plpgsql-statements-diagnostics"/>, retrieves information
about current execution state (whereas the <command>GET STACKED about current execution state (whereas the <command>GET STACKED
DIAGNOSTICS</command> command discussed above reports information about DIAGNOSTICS</command> command discussed above reports information about
the execution state as of a previous error). Its <literal>PG_CONTEXT</literal> the execution state as of a previous error). Its <literal>PG_CONTEXT</literal>
@ -2978,7 +2978,7 @@ DECLARE
<para> <para>
Bound cursor variables can also be used without explicitly opening the cursor, Bound cursor variables can also be used without explicitly opening the cursor,
via the <command>FOR</command> statement described in via the <command>FOR</command> statement described in
<xref linkend="plpgsql-cursor-for-loop">. <xref linkend="plpgsql-cursor-for-loop"/>.
</para> </para>
</note> </note>
@ -3031,7 +3031,7 @@ OPEN <replaceable>unbound_cursorvar</replaceable> <optional> <optional> NO </opt
<type>refcursor</type> variable). The query is specified as a string <type>refcursor</type> variable). The query is specified as a string
expression, in the same way as in the <command>EXECUTE</command> expression, in the same way as in the <command>EXECUTE</command>
command. As usual, this gives flexibility so the query plan can vary command. As usual, this gives flexibility so the query plan can vary
from one run to the next (see <xref linkend="plpgsql-plan-caching">), from one run to the next (see <xref linkend="plpgsql-plan-caching"/>),
and it also means that variable substitution is not done on the and it also means that variable substitution is not done on the
command string. As with <command>EXECUTE</command>, parameter values command string. As with <command>EXECUTE</command>, parameter values
can be inserted into the dynamic command via can be inserted into the dynamic command via
@ -3082,7 +3082,7 @@ OPEN <replaceable>bound_cursorvar</replaceable> <optional> ( <optional> <replace
notation, all arguments are specified in order. In named notation, notation, all arguments are specified in order. In named notation,
each argument's name is specified using <literal>:=</literal> to each argument's name is specified using <literal>:=</literal> to
separate it from the argument expression. Similar to calling separate it from the argument expression. Similar to calling
functions, described in <xref linkend="sql-syntax-calling-funcs">, it functions, described in <xref linkend="sql-syntax-calling-funcs"/>, it
is also allowed to mix positional and named notation. is also allowed to mix positional and named notation.
</para> </para>
@ -3160,7 +3160,7 @@ FETCH <optional> <replaceable>direction</replaceable> { FROM | IN } </optional>
<para> <para>
The <replaceable>direction</replaceable> clause can be any of the The <replaceable>direction</replaceable> clause can be any of the
variants allowed in the SQL <xref linkend="sql-fetch"> variants allowed in the SQL <xref linkend="sql-fetch"/>
command except the ones that can fetch command except the ones that can fetch
more than one row; namely, it can be more than one row; namely, it can be
<literal>NEXT</literal>, <literal>NEXT</literal>,
@ -3212,7 +3212,7 @@ MOVE <optional> <replaceable>direction</replaceable> { FROM | IN } </optional> <
<para> <para>
The <replaceable>direction</replaceable> clause can be any of the The <replaceable>direction</replaceable> clause can be any of the
variants allowed in the SQL <xref linkend="sql-fetch"> variants allowed in the SQL <xref linkend="sql-fetch"/>
command, namely command, namely
<literal>NEXT</literal>, <literal>NEXT</literal>,
<literal>PRIOR</literal>, <literal>PRIOR</literal>,
@ -3255,7 +3255,7 @@ DELETE FROM <replaceable>table</replaceable> WHERE CURRENT OF <replaceable>curso
restrictions on what the cursor's query can be (in particular, restrictions on what the cursor's query can be (in particular,
no grouping) and it's best to use <literal>FOR UPDATE</literal> in the no grouping) and it's best to use <literal>FOR UPDATE</literal> in the
cursor. For more information see the cursor. For more information see the
<xref linkend="sql-declare"> <xref linkend="sql-declare"/>
reference page. reference page.
</para> </para>
@ -3422,7 +3422,7 @@ END LOOP <optional> <replaceable>label</replaceable> </optional>;
expressions must appear if and only if the cursor was declared to take expressions must appear if and only if the cursor was declared to take
arguments. These values will be substituted in the query, in just arguments. These values will be substituted in the query, in just
the same way as during an <command>OPEN</command> (see <xref the same way as during an <command>OPEN</command> (see <xref
linkend="plpgsql-open-bound-cursor">). linkend="plpgsql-open-bound-cursor"/>).
</para> </para>
<para> <para>
@ -3475,9 +3475,9 @@ RAISE ;
priority levels. priority levels.
Whether messages of a particular priority are reported to the client, Whether messages of a particular priority are reported to the client,
written to the server log, or both is controlled by the written to the server log, or both is controlled by the
<xref linkend="guc-log-min-messages"> and <xref linkend="guc-log-min-messages"/> and
<xref linkend="guc-client-min-messages"> configuration <xref linkend="guc-client-min-messages"/> configuration
variables. See <xref linkend="runtime-config"> for more variables. See <xref linkend="runtime-config"/> for more
information. information.
</para> </para>
@ -3541,7 +3541,7 @@ RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
<term><literal>ERRCODE</literal></term> <term><literal>ERRCODE</literal></term>
<listitem> <listitem>
<para>Specifies the error code (SQLSTATE) to report, either by condition <para>Specifies the error code (SQLSTATE) to report, either by condition
name, as shown in <xref linkend="errcodes-appendix">, or directly as a name, as shown in <xref linkend="errcodes-appendix"/>, or directly as a
five-character SQLSTATE code.</para> five-character SQLSTATE code.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -3928,7 +3928,7 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</para> </para>
<para> <para>
<xref linkend="plpgsql-trigger-example"> shows an example of a <xref linkend="plpgsql-trigger-example"/> shows an example of a
trigger procedure in <application>PL/pgSQL</application>. trigger procedure in <application>PL/pgSQL</application>.
</para> </para>
@ -3981,7 +3981,7 @@ CREATE TRIGGER emp_stamp BEFORE INSERT OR UPDATE ON emp
Another way to log changes to a table involves creating a new table that Another way to log changes to a table involves creating a new table that
holds a row for each insert, update, or delete that occurs. This approach holds a row for each insert, update, or delete that occurs. This approach
can be thought of as auditing changes to a table. can be thought of as auditing changes to a table.
<xref linkend="plpgsql-trigger-audit-example"> shows an example of an <xref linkend="plpgsql-trigger-audit-example"/> shows an example of an
audit trigger procedure in <application>PL/pgSQL</application>. audit trigger procedure in <application>PL/pgSQL</application>.
</para> </para>
@ -4038,7 +4038,7 @@ AFTER INSERT OR UPDATE OR DELETE ON emp
approach still records the full audit trail of changes to the table, approach still records the full audit trail of changes to the table,
but also presents a simplified view of the audit trail, showing just but also presents a simplified view of the audit trail, showing just
the last modified timestamp derived from the audit trail for each entry. the last modified timestamp derived from the audit trail for each entry.
<xref linkend="plpgsql-view-trigger-audit-example"> shows an example <xref linkend="plpgsql-view-trigger-audit-example"/> shows an example
of an audit trigger on a view in <application>PL/pgSQL</application>. of an audit trigger on a view in <application>PL/pgSQL</application>.
</para> </para>
@ -4118,7 +4118,7 @@ INSTEAD OF INSERT OR UPDATE OR DELETE ON emp_view
times. times.
This technique is commonly used in Data Warehousing, where the tables This technique is commonly used in Data Warehousing, where the tables
of measured or observed data (called fact tables) might be extremely large. of measured or observed data (called fact tables) might be extremely large.
<xref linkend="plpgsql-trigger-summary-example"> shows an example of a <xref linkend="plpgsql-trigger-summary-example"/> shows an example of a
trigger procedure in <application>PL/pgSQL</application> that maintains trigger procedure in <application>PL/pgSQL</application> that maintains
a summary table for a fact table in a data warehouse. a summary table for a fact table in a data warehouse.
</para> </para>
@ -4272,7 +4272,7 @@ SELECT * FROM sales_summary_bytime;
statement. The <command>CREATE TRIGGER</command> command assigns names to one statement. The <command>CREATE TRIGGER</command> command assigns names to one
or both transition tables, and then the function can refer to those names or both transition tables, and then the function can refer to those names
as though they were read-only temporary tables. as though they were read-only temporary tables.
<xref linkend="plpgsql-trigger-audit-transition-example"> shows an example. <xref linkend="plpgsql-trigger-audit-transition-example"/> shows an example.
</para> </para>
<example id="plpgsql-trigger-audit-transition-example"> <example id="plpgsql-trigger-audit-transition-example">
@ -4280,7 +4280,7 @@ SELECT * FROM sales_summary_bytime;
<para> <para>
This example produces the same results as This example produces the same results as
<xref linkend="plpgsql-trigger-audit-example">, but instead of using a <xref linkend="plpgsql-trigger-audit-example"/>, but instead of using a
trigger that fires for every row, it uses a trigger that fires once trigger that fires for every row, it uses a trigger that fires once
per statement, after collecting the relevant information in a transition per statement, after collecting the relevant information in a transition
table. This can be significantly faster than the row-trigger approach table. This can be significantly faster than the row-trigger approach
@ -4383,7 +4383,7 @@ CREATE TRIGGER emp_audit_del
</para> </para>
<para> <para>
<xref linkend="plpgsql-event-trigger-example"> shows an example of an <xref linkend="plpgsql-event-trigger-example"/> shows an example of an
event trigger procedure in <application>PL/pgSQL</application>. event trigger procedure in <application>PL/pgSQL</application>.
</para> </para>
@ -4482,7 +4482,7 @@ INSERT INTO dest (col) SELECT foo + bar FROM src;
In the above example, <literal>src.foo</literal> would be an unambiguous reference In the above example, <literal>src.foo</literal> would be an unambiguous reference
to the table column. To create an unambiguous reference to a variable, to the table column. To create an unambiguous reference to a variable,
declare it in a labeled block and use the block's label declare it in a labeled block and use the block's label
(see <xref linkend="plpgsql-structure">). For example, (see <xref linkend="plpgsql-structure"/>). For example,
<programlisting> <programlisting>
&lt;&lt;block&gt;&gt; &lt;&lt;block&gt;&gt;
DECLARE DECLARE
@ -4575,7 +4575,7 @@ $$ LANGUAGE plpgsql;
to <command>EXECUTE</command> or one of its variants. If you need to to <command>EXECUTE</command> or one of its variants. If you need to
insert a varying value into such a command, do so as part of insert a varying value into such a command, do so as part of
constructing the string value, or use <literal>USING</literal>, as illustrated in constructing the string value, or use <literal>USING</literal>, as illustrated in
<xref linkend="plpgsql-statements-executing-dyn">. <xref linkend="plpgsql-statements-executing-dyn"/>.
</para> </para>
<para> <para>
@ -4636,7 +4636,7 @@ $$ LANGUAGE plpgsql;
this will happen only if the execution plan is not very sensitive to this will happen only if the execution plan is not very sensitive to
the values of the <application>PL/pgSQL</application> variables referenced in it. the values of the <application>PL/pgSQL</application> variables referenced in it.
If it is, generating a plan each time is a net win. See <xref If it is, generating a plan each time is a net win. See <xref
linkend="sql-prepare"> for more information about the behavior of linkend="sql-prepare"/> for more information about the behavior of
prepared statements. prepared statements.
</para> </para>
@ -4796,7 +4796,7 @@ $$ LANGUAGE plpgsql;
easily find yourself needing half a dozen or more adjacent quote marks. easily find yourself needing half a dozen or more adjacent quote marks.
It's recommended that you instead write the function body as a It's recommended that you instead write the function body as a
<quote>dollar-quoted</quote> string literal (see <xref <quote>dollar-quoted</quote> string literal (see <xref
linkend="sql-syntax-dollar-quoting">). In the dollar-quoting linkend="sql-syntax-dollar-quoting"/>). In the dollar-quoting
approach, you never double any quote marks, but instead take care to approach, you never double any quote marks, but instead take care to
choose a different dollar-quoting delimiter for each level of choose a different dollar-quoting delimiter for each level of
nesting you need. For example, you might write the <command>CREATE nesting you need. For example, you might write the <command>CREATE
@ -4907,7 +4907,7 @@ a_output := a_output || $$ AND name LIKE 'foobar'$$
accounts for 8 quotation marks) and this is adjacent to the end of that accounts for 8 quotation marks) and this is adjacent to the end of that
string constant (2 more). You will probably only need that if string constant (2 more). You will probably only need that if
you are writing a function that generates other functions, as in you are writing a function that generates other functions, as in
<xref linkend="plpgsql-porting-ex2">. <xref linkend="plpgsql-porting-ex2"/>.
For example: For example:
<programlisting> <programlisting>
a_output := a_output || '' if v_'' || a_output := a_output || '' if v_'' ||
@ -5029,7 +5029,7 @@ CREATE FUNCTION
to <application>PL/pgSQL</application>'s to <application>PL/pgSQL</application>'s
<literal>plpgsql.variable_conflict</literal> = <literal>use_column</literal> <literal>plpgsql.variable_conflict</literal> = <literal>use_column</literal>
behavior, which is not the default, behavior, which is not the default,
as explained in <xref linkend="plpgsql-var-subst">. as explained in <xref linkend="plpgsql-var-subst"/>.
It's often best to avoid such ambiguities in the first place, It's often best to avoid such ambiguities in the first place,
but if you have to port a large amount of code that depends on but if you have to port a large amount of code that depends on
this behavior, setting <literal>variable_conflict</literal> may be the this behavior, setting <literal>variable_conflict</literal> may be the
@ -5042,7 +5042,7 @@ CREATE FUNCTION
In <productname>PostgreSQL</productname> the function body must be written as In <productname>PostgreSQL</productname> the function body must be written as
a string literal. Therefore you need to use dollar quoting or escape a string literal. Therefore you need to use dollar quoting or escape
single quotes in the function body. (See <xref single quotes in the function body. (See <xref
linkend="plpgsql-quote-tips">.) linkend="plpgsql-quote-tips"/>.)
</para> </para>
</listitem> </listitem>
@ -5080,7 +5080,7 @@ CREATE FUNCTION
from the first number to the second, requiring the loop bounds from the first number to the second, requiring the loop bounds
to be swapped when porting. This incompatibility is unfortunate to be swapped when porting. This incompatibility is unfortunate
but is unlikely to be changed. (See <xref but is unlikely to be changed. (See <xref
linkend="plpgsql-integer-for">.) linkend="plpgsql-integer-for"/>.)
</para> </para>
</listitem> </listitem>
@ -5108,7 +5108,7 @@ CREATE FUNCTION
<title>Porting Examples</title> <title>Porting Examples</title>
<para> <para>
<xref linkend="pgsql-porting-ex1"> shows how to port a simple <xref linkend="pgsql-porting-ex1"/> shows how to port a simple
function from <application>PL/SQL</application> to <application>PL/pgSQL</application>. function from <application>PL/SQL</application> to <application>PL/pgSQL</application>.
</para> </para>
@ -5197,7 +5197,7 @@ $$ LANGUAGE plpgsql;
</example> </example>
<para> <para>
<xref linkend="plpgsql-porting-ex2"> shows how to port a <xref linkend="plpgsql-porting-ex2"/> shows how to port a
function that creates another function and how to handle the function that creates another function and how to handle the
ensuing quoting problems. ensuing quoting problems.
</para> </para>
@ -5292,12 +5292,12 @@ $func$ LANGUAGE plpgsql;
</example> </example>
<para> <para>
<xref linkend="plpgsql-porting-ex3"> shows how to port a function <xref linkend="plpgsql-porting-ex3"/> shows how to port a function
with <literal>OUT</literal> parameters and string manipulation. with <literal>OUT</literal> parameters and string manipulation.
<productname>PostgreSQL</productname> does not have a built-in <productname>PostgreSQL</productname> does not have a built-in
<function>instr</function> function, but you can create one <function>instr</function> function, but you can create one
using a combination of other using a combination of other
functions. In <xref linkend="plpgsql-porting-appendix"> there is a functions. In <xref linkend="plpgsql-porting-appendix"/> there is a
<application>PL/pgSQL</application> implementation of <application>PL/pgSQL</application> implementation of
<function>instr</function> that you can use to make your porting <function>instr</function> that you can use to make your porting
easier. easier.
@ -5406,7 +5406,7 @@ SELECT * FROM cs_parse_url('http://foobar.com/query.cgi?baz');
</example> </example>
<para> <para>
<xref linkend="plpgsql-porting-ex4"> shows how to port a procedure <xref linkend="plpgsql-porting-ex4"/> shows how to port a procedure
that uses numerous features that are specific to Oracle. that uses numerous features that are specific to Oracle.
</para> </para>
@ -5419,14 +5419,14 @@ SELECT * FROM cs_parse_url('http://foobar.com/query.cgi?baz');
<programlisting> <programlisting>
CREATE OR REPLACE PROCEDURE cs_create_job(v_job_id IN INTEGER) IS CREATE OR REPLACE PROCEDURE cs_create_job(v_job_id IN INTEGER) IS
a_running_job_count INTEGER; a_running_job_count INTEGER;
PRAGMA AUTONOMOUS_TRANSACTION; -- <co id="co.plpgsql-porting-pragma"> PRAGMA AUTONOMOUS_TRANSACTION; -- <co id="co.plpgsql-porting-pragma"/>
BEGIN 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; SELECT count(*) INTO a_running_job_count FROM cs_jobs WHERE end_stamp IS NULL;
IF a_running_job_count &gt; 0 THEN IF a_running_job_count &gt; 0 THEN
COMMIT; -- free lock <co id="co.plpgsql-porting-commit"> COMMIT; -- free lock <co id="co.plpgsql-porting-commit"/>
raise_application_error(-20000, raise_application_error(-20000,
'Unable to create a new job: a job is currently running.'); 'Unable to create a new job: a job is currently running.');
END IF; END IF;
@ -5493,7 +5493,7 @@ BEGIN
SELECT count(*) INTO a_running_job_count FROM cs_jobs WHERE end_stamp IS NULL; SELECT count(*) INTO a_running_job_count FROM cs_jobs WHERE end_stamp IS NULL;
IF a_running_job_count &gt; 0 THEN IF a_running_job_count &gt; 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; END IF;
DELETE FROM cs_active_job; DELETE FROM cs_active_job;
@ -5502,7 +5502,7 @@ BEGIN
BEGIN BEGIN
INSERT INTO cs_jobs (job_id, start_stamp) VALUES (v_job_id, now()); INSERT INTO cs_jobs (job_id, start_stamp) VALUES (v_job_id, now());
EXCEPTION 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 -- don't worry if it already exists
END; END;
END; END;
@ -5522,7 +5522,7 @@ $$ LANGUAGE plpgsql;
<para> <para>
The exception names supported by <application>PL/pgSQL</application> are The exception names supported by <application>PL/pgSQL</application> are
different from Oracle's. The set of built-in exception names different from Oracle's. The set of built-in exception names
is much larger (see <xref linkend="errcodes-appendix">). There is much larger (see <xref linkend="errcodes-appendix"/>). There
is not currently a way to declare user-defined exception names, is not currently a way to declare user-defined exception names,
although you can throw user-chosen SQLSTATE values instead. although you can throw user-chosen SQLSTATE values instead.
</para> </para>
@ -5588,7 +5588,7 @@ END;
<application>PL/SQL</application> version, but you have to remember to use <application>PL/SQL</application> version, but you have to remember to use
<function>quote_literal</function> and <function>quote_literal</function> and
<function>quote_ident</function> as described in <xref <function>quote_ident</function> as described in <xref
linkend="plpgsql-statements-executing-dyn">. Constructs of the linkend="plpgsql-statements-executing-dyn"/>. Constructs of the
type <literal>EXECUTE 'SELECT * FROM $1';</literal> will not work type <literal>EXECUTE 'SELECT * FROM $1';</literal> will not work
reliably unless you use these functions. reliably unless you use these functions.
</para> </para>
@ -5603,7 +5603,7 @@ END;
the function always returns the same result when given the same the function always returns the same result when given the same
arguments) and <quote>strictness</quote> (whether the function arguments) and <quote>strictness</quote> (whether the function
returns null if any argument is null). Consult the <xref returns null if any argument is null). Consult the <xref
linkend="sql-createfunction"> linkend="sql-createfunction"/>
reference page for details. reference page for details.
</para> </para>

30
doc/src/sgml/plpython.sgml
View File

@ -15,7 +15,7 @@
<para> <para>
To install PL/Python in a particular database, use To install PL/Python in a particular database, use
<literal>CREATE EXTENSION plpythonu</literal> (but <literal>CREATE EXTENSION plpythonu</literal> (but
see also <xref linkend="plpython-python23">). see also <xref linkend="plpython-python23"/>).
</para> </para>
<tip> <tip>
@ -103,7 +103,7 @@
The built variant depends on which Python version was found during The built variant depends on which Python version was found during
the installation or which version was explicitly set using the installation or which version was explicitly set using
the <envar>PYTHON</envar> environment variable; the <envar>PYTHON</envar> environment variable;
see <xref linkend="install-procedure">. To make both variants of see <xref linkend="install-procedure"/>. To make both variants of
PL/Python available in one installation, the source tree has to be PL/Python available in one installation, the source tree has to be
configured and built twice. configured and built twice.
</para> </para>
@ -186,7 +186,7 @@
<para> <para>
Functions in PL/Python are declared via the Functions in PL/Python are declared via the
standard <xref linkend="sql-createfunction"> syntax: standard <xref linkend="sql-createfunction"/> syntax:
<programlisting> <programlisting>
CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-list</replaceable>) CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-list</replaceable>)
@ -420,7 +420,7 @@ $$ LANGUAGE plpythonu;
sortas="PL/Python">in PL/Python</secondary></indexterm> is passed to a sortas="PL/Python">in PL/Python</secondary></indexterm> is passed to a
function, the argument value will appear as <symbol>None</symbol> in function, the argument value will appear as <symbol>None</symbol> in
Python. For example, the function definition of <function>pymax</function> Python. For example, the function definition of <function>pymax</function>
shown in <xref linkend="plpython-funcs"> will return the wrong answer for null shown in <xref linkend="plpython-funcs"/> will return the wrong answer for null
inputs. We could add <literal>STRICT</literal> to the function definition inputs. We could add <literal>STRICT</literal> to the function definition
to make <productname>PostgreSQL</productname> do something more reasonable: to make <productname>PostgreSQL</productname> do something more reasonable:
if a null value is passed, the function will not be called at all, if a null value is passed, the function will not be called at all,
@ -774,7 +774,7 @@ SELECT * FROM multiout_simple_setof(3);
<para> <para>
PL/Python also supports anonymous code blocks called with the PL/Python also supports anonymous code blocks called with the
<xref linkend="sql-do"> statement: <xref linkend="sql-do"/> statement:
<programlisting> <programlisting>
DO $$ DO $$
@ -1056,16 +1056,16 @@ rv = plan.execute(["name"], 5)
<para> <para>
Query parameters and result row fields are converted between PostgreSQL Query parameters and result row fields are converted between PostgreSQL
and Python data types as described in <xref linkend="plpython-data">. and Python data types as described in <xref linkend="plpython-data"/>.
</para> </para>
<para> <para>
When you prepare a plan using the PL/Python module it is automatically When you prepare a plan using the PL/Python module it is automatically
saved. Read the SPI documentation (<xref linkend="spi">) for a saved. Read the SPI documentation (<xref linkend="spi"/>) for a
description of what this means. In order to make effective use of this description of what this means. In order to make effective use of this
across function calls one needs to use one of the persistent storage across function calls one needs to use one of the persistent storage
dictionaries <literal>SD</literal> or <literal>GD</literal> (see dictionaries <literal>SD</literal> or <literal>GD</literal> (see
<xref linkend="plpython-sharing">). For example: <xref linkend="plpython-sharing"/>). For example:
<programlisting> <programlisting>
CREATE FUNCTION usesavedplan() RETURNS trigger AS $$ CREATE FUNCTION usesavedplan() RETURNS trigger AS $$
if "plan" in SD: if "plan" in SD:
@ -1190,7 +1190,7 @@ $$ LANGUAGE plpythonu;
<para> <para>
The actual class of the exception being raised corresponds to the The actual class of the exception being raised corresponds to the
specific condition that caused the error. Refer specific condition that caused the error. Refer
to <xref linkend="errcodes-table"> for a list of possible to <xref linkend="errcodes-table"/> for a list of possible
conditions. The module conditions. The module
<literal>plpy.spiexceptions</literal> defines an exception class <literal>plpy.spiexceptions</literal> defines an exception class
for each <productname>PostgreSQL</productname> condition, deriving for each <productname>PostgreSQL</productname> condition, deriving
@ -1241,7 +1241,7 @@ $$ LANGUAGE plpythonu;
<para> <para>
Recovering from errors caused by database access as described in Recovering from errors caused by database access as described in
<xref linkend="plpython-trapping"> can lead to an undesirable <xref linkend="plpython-trapping"/> can lead to an undesirable
situation where some operations succeed before one of them fails, situation where some operations succeed before one of them fails,
and after recovering from that error the data is left in an and after recovering from that error the data is left in an
inconsistent state. PL/Python offers a solution to this problem in inconsistent state. PL/Python offers a solution to this problem in
@ -1391,9 +1391,9 @@ $$ LANGUAGE plpythonu;
The other functions only generate messages of different priority levels. The other functions only generate messages of different priority levels.
Whether messages of a particular priority are reported to the client, Whether messages of a particular priority are reported to the client,
written to the server log, or both is controlled by the written to the server log, or both is controlled by the
<xref linkend="guc-log-min-messages"> and <xref linkend="guc-log-min-messages"/> and
<xref linkend="guc-client-min-messages"> configuration <xref linkend="guc-client-min-messages"/> configuration
variables. See <xref linkend="runtime-config"> for more information. variables. See <xref linkend="runtime-config"/> for more information.
</para> </para>
<para> <para>
@ -1442,9 +1442,9 @@ PL/Python function "raise_custom_exception"
<literal>plpy.quote_nullable(<replaceable>string</replaceable>)</literal>, and <literal>plpy.quote_nullable(<replaceable>string</replaceable>)</literal>, and
<literal>plpy.quote_ident(<replaceable>string</replaceable>)</literal>. They <literal>plpy.quote_ident(<replaceable>string</replaceable>)</literal>. They
are equivalent to the built-in quoting functions described in <xref are equivalent to the built-in quoting functions described in <xref
linkend="functions-string">. They are useful when constructing linkend="functions-string"/>. They are useful when constructing
ad-hoc queries. A PL/Python equivalent of dynamic SQL from <xref ad-hoc queries. A PL/Python equivalent of dynamic SQL from <xref
linkend="plpgsql-quote-literal-example"> would be: linkend="plpgsql-quote-literal-example"/> would be:
<programlisting> <programlisting>
plpy.execute("UPDATE tbl SET %s = %s WHERE key = %s" % ( plpy.execute("UPDATE tbl SET %s = %s WHERE key = %s" % (
plpy.quote_ident(colname), plpy.quote_ident(colname),

16
doc/src/sgml/pltcl.sgml
View File

@ -79,7 +79,7 @@
<para> <para>
To create a function in the <application>PL/Tcl</application> language, use To create a function in the <application>PL/Tcl</application> language, use
the standard <xref linkend="sql-createfunction"> syntax: the standard <xref linkend="sql-createfunction"/> syntax:
<programlisting> <programlisting>
CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types</replaceable>) RETURNS <replaceable>return-type</replaceable> AS $$ CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types</replaceable>) RETURNS <replaceable>return-type</replaceable> AS $$
@ -483,7 +483,7 @@ $$ LANGUAGE pltcl;
executed within a SQL subtransaction. If the script returns an executed within a SQL subtransaction. If the script returns an
error, that entire subtransaction is rolled back before returning the error, that entire subtransaction is rolled back before returning the
error out to the surrounding Tcl code. error out to the surrounding Tcl code.
See <xref linkend="pltcl-subtransactions"> for more details and an See <xref linkend="pltcl-subtransactions"/> for more details and an
example. example.
</para> </para>
</listitem> </listitem>
@ -559,10 +559,10 @@ SELECT 'doesn''t' AS ret
priority levels. priority levels.
Whether messages of a particular priority are reported to the client, Whether messages of a particular priority are reported to the client,
written to the server log, or both is controlled by the written to the server log, or both is controlled by the
<xref linkend="guc-log-min-messages"> and <xref linkend="guc-log-min-messages"/> and
<xref linkend="guc-client-min-messages"> configuration <xref linkend="guc-client-min-messages"/> configuration
variables. See <xref linkend="runtime-config"> variables. See <xref linkend="runtime-config"/>
and <xref linkend="pltcl-error-handling"> and <xref linkend="pltcl-error-handling"/>
for more information. for more information.
</para> </para>
</listitem> </listitem>
@ -888,7 +888,7 @@ CREATE EVENT TRIGGER tcl_a_snitch ON ddl_command_start EXECUTE PROCEDURE tclsnit
Fields <varname>SQLSTATE</varname>, <varname>condition</varname>, Fields <varname>SQLSTATE</varname>, <varname>condition</varname>,
and <varname>message</varname> are always supplied and <varname>message</varname> are always supplied
(the first two represent the error code and condition name as shown (the first two represent the error code and condition name as shown
in <xref linkend="errcodes-appendix">). in <xref linkend="errcodes-appendix"/>).
Fields that may be present include Fields that may be present include
<varname>detail</varname>, <varname>hint</varname>, <varname>context</varname>, <varname>detail</varname>, <varname>hint</varname>, <varname>context</varname>,
<varname>schema</varname>, <varname>table</varname>, <varname>column</varname>, <varname>schema</varname>, <varname>table</varname>, <varname>column</varname>,
@ -929,7 +929,7 @@ if {[catch { spi_exec $sql_command }]} {
<para> <para>
Recovering from errors caused by database access as described in Recovering from errors caused by database access as described in
<xref linkend="pltcl-error-handling"> can lead to an undesirable <xref linkend="pltcl-error-handling"/> can lead to an undesirable
situation where some operations succeed before one of them fails, situation where some operations succeed before one of them fails,
and after recovering from that error the data is left in an and after recovering from that error the data is left in an
inconsistent state. PL/Tcl offers a solution to this problem in inconsistent state. PL/Tcl offers a solution to this problem in

40
doc/src/sgml/postgres-fdw.sgml
View File

@ -15,7 +15,7 @@
<para> <para>
The functionality provided by this module overlaps substantially The functionality provided by this module overlaps substantially
with the functionality of the older <xref linkend="dblink"> module. with the functionality of the older <xref linkend="dblink"/> module.
But <filename>postgres_fdw</filename> provides more transparent and But <filename>postgres_fdw</filename> provides more transparent and
standards-compliant syntax for accessing remote tables, and can give standards-compliant syntax for accessing remote tables, and can give
better performance in many cases. better performance in many cases.
@ -27,12 +27,12 @@
<listitem> <listitem>
<para> <para>
Install the <filename>postgres_fdw</filename> extension using <xref Install the <filename>postgres_fdw</filename> extension using <xref
linkend="sql-createextension">. linkend="sql-createextension"/>.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Create a foreign server object, using <xref linkend="sql-createserver">, Create a foreign server object, using <xref linkend="sql-createserver"/>,
to represent each remote database you want to connect to. to represent each remote database you want to connect to.
Specify connection information, except <literal>user</literal> and Specify connection information, except <literal>user</literal> and
<literal>password</literal>, as options of the server object. <literal>password</literal>, as options of the server object.
@ -40,7 +40,7 @@
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Create a user mapping, using <xref linkend="sql-createusermapping">, for Create a user mapping, using <xref linkend="sql-createusermapping"/>, for
each database user you want to allow to access each foreign server. each database user you want to allow to access each foreign server.
Specify the remote user name and password to use as Specify the remote user name and password to use as
<literal>user</literal> and <literal>password</literal> options of the <literal>user</literal> and <literal>password</literal> options of the
@ -49,8 +49,8 @@
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Create a foreign table, using <xref linkend="sql-createforeigntable"> Create a foreign table, using <xref linkend="sql-createforeigntable"/>
or <xref linkend="sql-importforeignschema">, or <xref linkend="sql-importforeignschema"/>,
for each remote table you want to access. The columns of the foreign for each remote table you want to access. The columns of the foreign
table must match the referenced remote table. You can, however, use table must match the referenced remote table. You can, however, use
table and/or column names different from the remote table's, if you table and/or column names different from the remote table's, if you
@ -101,7 +101,7 @@
<para> <para>
A foreign server using the <filename>postgres_fdw</filename> foreign data wrapper A foreign server using the <filename>postgres_fdw</filename> foreign data wrapper
can have the same options that <application>libpq</application> accepts in can have the same options that <application>libpq</application> accepts in
connection strings, as described in <xref linkend="libpq-paramkeywords">, connection strings, as described in <xref linkend="libpq-paramkeywords"/>,
except that these options are not allowed: except that these options are not allowed:
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
@ -254,7 +254,7 @@
<literal>fdw_tuple_cost</literal> to the cost estimates. This local <literal>fdw_tuple_cost</literal> to the cost estimates. This local
estimation is unlikely to be very accurate unless local copies of the estimation is unlikely to be very accurate unless local copies of the
remote table's statistics are available. Running remote table's statistics are available. Running
<xref linkend="sql-analyze"> on the foreign table is the way to update <xref linkend="sql-analyze"/> on the foreign table is the way to update
the local statistics; this will perform a scan of the remote table and the local statistics; this will perform a scan of the remote table and
then calculate and store statistics just as though the table were local. then calculate and store statistics just as though the table were local.
Keeping local statistics can be a useful way to reduce per-query planning Keeping local statistics can be a useful way to reduce per-query planning
@ -359,7 +359,7 @@
<para> <para>
<filename>postgres_fdw</filename> is able to import foreign table definitions <filename>postgres_fdw</filename> is able to import foreign table definitions
using <xref linkend="sql-importforeignschema">. This command creates using <xref linkend="sql-importforeignschema"/>. This command creates
foreign table definitions on the local server that match tables or foreign table definitions on the local server that match tables or
views present on the remote server. If the remote tables to be imported views present on the remote server. If the remote tables to be imported
have columns of user-defined data types, the local server must have have columns of user-defined data types, the local server must have
@ -423,7 +423,7 @@
So if you wish to import <literal>CHECK</literal> constraints, you must do so So if you wish to import <literal>CHECK</literal> constraints, you must do so
manually, and you should verify the semantics of each one carefully. manually, and you should verify the semantics of each one carefully.
For more detail about the treatment of <literal>CHECK</literal> constraints on For more detail about the treatment of <literal>CHECK</literal> constraints on
foreign tables, see <xref linkend="sql-createforeigntable">. foreign tables, see <xref linkend="sql-createforeigntable"/>.
</para> </para>
<para> <para>
@ -528,7 +528,7 @@
<para> <para>
In the remote sessions opened by <filename>postgres_fdw</filename>, In the remote sessions opened by <filename>postgres_fdw</filename>,
the <xref linkend="guc-search-path"> parameter is set to the <xref linkend="guc-search-path"/> parameter is set to
just <literal>pg_catalog</literal>, so that only built-in objects are visible just <literal>pg_catalog</literal>, so that only built-in objects are visible
without schema qualification. This is not an issue for queries without schema qualification. This is not an issue for queries
generated by <filename>postgres_fdw</filename> itself, because it always generated by <filename>postgres_fdw</filename> itself, because it always
@ -538,7 +538,7 @@
any functions used in that view will be executed with the restricted any functions used in that view will be executed with the restricted
search path. It is recommended to schema-qualify all names in such search path. It is recommended to schema-qualify all names in such
functions, or else attach <literal>SET search_path</literal> options functions, or else attach <literal>SET search_path</literal> options
(see <xref linkend="sql-createfunction">) to such functions (see <xref linkend="sql-createfunction"/>) to such functions
to establish their expected search path environment. to establish their expected search path environment.
</para> </para>
@ -548,22 +548,22 @@
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem> <listitem>
<para> <para>
<xref linkend="guc-timezone"> is set to <literal>UTC</literal> <xref linkend="guc-timezone"/> is set to <literal>UTC</literal>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<xref linkend="guc-datestyle"> is set to <literal>ISO</literal> <xref linkend="guc-datestyle"/> is set to <literal>ISO</literal>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<xref linkend="guc-intervalstyle"> is set to <literal>postgres</literal> <xref linkend="guc-intervalstyle"/> is set to <literal>postgres</literal>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<xref linkend="guc-extra-float-digits"> is set to <literal>3</literal> for remote <xref linkend="guc-extra-float-digits"/> is set to <literal>3</literal> for remote
servers 9.0 and newer and is set to <literal>2</literal> for older versions servers 9.0 and newer and is set to <literal>2</literal> for older versions
</para> </para>
</listitem> </listitem>
@ -612,7 +612,7 @@ CREATE EXTENSION postgres_fdw;
</programlisting> </programlisting>
<para> <para>
Then create a foreign server using <xref linkend="sql-createserver">. Then create a foreign server using <xref linkend="sql-createserver"/>.
In this example we wish to connect to a <productname>PostgreSQL</productname> server In this example we wish to connect to a <productname>PostgreSQL</productname> server
on host <literal>192.83.123.89</literal> listening on on host <literal>192.83.123.89</literal> listening on
port <literal>5432</literal>. The database to which the connection is made port <literal>5432</literal>. The database to which the connection is made
@ -626,7 +626,7 @@ CREATE SERVER foreign_server
</para> </para>
<para> <para>
A user mapping, defined with <xref linkend="sql-createusermapping">, is A user mapping, defined with <xref linkend="sql-createusermapping"/>, is
needed as well to identify the role that will be used on the remote needed as well to identify the role that will be used on the remote
server: server:
@ -639,7 +639,7 @@ CREATE USER MAPPING FOR local_user
<para> <para>
Now it is possible to create a foreign table with Now it is possible to create a foreign table with
<xref linkend="sql-createforeigntable">. In this example we <xref linkend="sql-createforeigntable"/>. In this example we
wish to access the table named <structname>some_schema.some_table</structname> wish to access the table named <structname>some_schema.some_table</structname>
on the remote server. The local name for it will on the remote server. The local name for it will
be <structname>foreign_table</structname>: be <structname>foreign_table</structname>:
@ -658,7 +658,7 @@ CREATE FOREIGN TABLE foreign_table (
Column names must match as well, unless you attach <literal>column_name</literal> Column names must match as well, unless you attach <literal>column_name</literal>
options to the individual columns to show how they are named in the remote options to the individual columns to show how they are named in the remote
table. table.
In many cases, use of <xref linkend="sql-importforeignschema"> is In many cases, use of <xref linkend="sql-importforeignschema"/> is
preferable to constructing foreign table definitions manually. preferable to constructing foreign table definitions manually.
</para> </para>
</sect2> </sect2>

26
doc/src/sgml/postgres.sgml
View File

@ -1,6 +1,8 @@
<!-- doc/src/sgml/postgres.sgml --> <!-- doc/src/sgml/postgres.sgml -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[
<!ENTITY % version SYSTEM "version.sgml"> <!ENTITY % version SYSTEM "version.sgml">
%version; %version;
@ -42,11 +44,11 @@
<para> <para>
After you have worked through this tutorial you might want to move After you have worked through this tutorial you might want to move
on to reading <xref linkend="sql"> to gain a more formal knowledge on to reading <xref linkend="sql"/> to gain a more formal knowledge
of the SQL language, or <xref linkend="client-interfaces"> for of the SQL language, or <xref linkend="client-interfaces"/> for
information about developing applications for information about developing applications for
<productname>PostgreSQL</productname>. Those who set up and <productname>PostgreSQL</productname>. Those who set up and
manage their own server should also read <xref linkend="admin">. manage their own server should also read <xref linkend="admin"/>.
</para> </para>
</partintro> </partintro>
@ -80,14 +82,14 @@
chapters individually as they choose. The information in this chapters individually as they choose. The information in this
part is presented in a narrative fashion in topical units. part is presented in a narrative fashion in topical units.
Readers looking for a complete description of a particular command Readers looking for a complete description of a particular command
should see <xref linkend="reference">. should see <xref linkend="reference"/>.
</para> </para>
<para> <para>
Readers of this part should know how to connect to a Readers of this part should know how to connect to a
<productname>PostgreSQL</productname> database and issue <productname>PostgreSQL</productname> database and issue
<acronym>SQL</acronym> commands. Readers that are unfamiliar with <acronym>SQL</acronym> commands. Readers that are unfamiliar with
these issues are encouraged to read <xref linkend="tutorial"> these issues are encouraged to read <xref linkend="tutorial"/>
first. <acronym>SQL</acronym> commands are typically entered first. <acronym>SQL</acronym> commands are typically entered
using the <productname>PostgreSQL</productname> interactive terminal using the <productname>PostgreSQL</productname> interactive terminal
<application>psql</application>, but other programs that have <application>psql</application>, but other programs that have
@ -130,7 +132,7 @@
self-contained and can be read individually as desired. The self-contained and can be read individually as desired. The
information in this part is presented in a narrative fashion in information in this part is presented in a narrative fashion in
topical units. Readers looking for a complete description of a topical units. Readers looking for a complete description of a
particular command should see <xref linkend="reference">. particular command should see <xref linkend="reference"/>.
</para> </para>
<para> <para>
@ -140,8 +142,8 @@
The rest of this part is about tuning and management; that material The rest of this part is about tuning and management; that material
assumes that the reader is familiar with the general use of assumes that the reader is familiar with the general use of
the <productname>PostgreSQL</productname> database system. Readers are the <productname>PostgreSQL</productname> database system. Readers are
encouraged to look at <xref linkend="tutorial"> and <xref encouraged to look at <xref linkend="tutorial"/> and <xref
linkend="sql"> for additional information. linkend="sql"/> for additional information.
</para> </para>
</partintro> </partintro>
@ -174,10 +176,10 @@
with <productname>PostgreSQL</productname>. Each of these chapters can be with <productname>PostgreSQL</productname>. Each of these chapters can be
read independently. Note that there are many other programming read independently. Note that there are many other programming
interfaces for client programs that are distributed separately and interfaces for client programs that are distributed separately and
contain their own documentation (<xref linkend="external-projects"> contain their own documentation (<xref linkend="external-projects"/>
lists some of the more popular ones). Readers of this part should be lists some of the more popular ones). Readers of this part should be
familiar with using <acronym>SQL</acronym> commands to manipulate familiar with using <acronym>SQL</acronym> commands to manipulate
and query the database (see <xref linkend="sql">) and of course and query the database (see <xref linkend="sql"/>) and of course
with the programming language that the interface uses. with the programming language that the interface uses.
</para> </para>
</partintro> </partintro>
@ -203,7 +205,7 @@
<productname>PostgreSQL</productname> distribution as well as <productname>PostgreSQL</productname> distribution as well as
general issues concerning server-side programming languages. It general issues concerning server-side programming languages. It
is essential to read at least the earlier sections of <xref is essential to read at least the earlier sections of <xref
linkend="extend"> (covering functions) before diving into the linkend="extend"/> (covering functions) before diving into the
material about server-side programming languages. material about server-side programming languages.
</para> </para>
</partintro> </partintro>

2
doc/src/sgml/problems.sgml
View File

@ -170,7 +170,7 @@
form of the message. In <application>psql</application>, say <literal>\set form of the message. In <application>psql</application>, say <literal>\set
VERBOSITY verbose</literal> beforehand. If you are extracting the message VERBOSITY verbose</literal> beforehand. If you are extracting the message
from the server log, set the run-time parameter from the server log, set the run-time parameter
<xref linkend="guc-log-error-verbosity"> to <literal>verbose</literal> so that all <xref linkend="guc-log-error-verbosity"/> to <literal>verbose</literal> so that all
details are logged. details are logged.
</para> </para>
</note> </note>

60
doc/src/sgml/protocol.sgml
View File

@ -207,7 +207,7 @@
<para> <para>
This section describes the message flow and the semantics of each This section describes the message flow and the semantics of each
message type. (Details of the exact representation of each message message type. (Details of the exact representation of each message
appear in <xref linkend="protocol-message-formats">.) There are appear in <xref linkend="protocol-message-formats"/>.) There are
several different sub-protocols depending on the state of the several different sub-protocols depending on the state of the
connection: start-up, query, function call, connection: start-up, query, function call,
<command>COPY</command>, and termination. There are also special <command>COPY</command>, and termination. There are also special
@ -383,7 +383,7 @@
SASLInitialResponse with the name of the selected mechanism, and the SASLInitialResponse with the name of the selected mechanism, and the
first part of the SASL data stream in response to this. If further first part of the SASL data stream in response to this. If further
messages are needed, the server will respond with messages are needed, the server will respond with
AuthenticationSASLContinue. See <xref linkend="sasl-authentication"> AuthenticationSASLContinue. See <xref linkend="sasl-authentication"/>
for details. for details.
</para> </para>
</listitem> </listitem>
@ -478,9 +478,9 @@
<para> <para>
This message informs the frontend about the current (initial) This message informs the frontend about the current (initial)
setting of backend parameters, such as <xref setting of backend parameters, such as <xref
linkend="guc-client-encoding"> or <xref linkend="guc-datestyle">. linkend="guc-client-encoding"/> or <xref linkend="guc-datestyle"/>.
The frontend can ignore this message, or record the settings The frontend can ignore this message, or record the settings
for its future use; see <xref linkend="protocol-async"> for for its future use; see <xref linkend="protocol-async"/> for
more details. The frontend should not respond to this more details. The frontend should not respond to this
message, but should continue listening for a ReadyForQuery message, but should continue listening for a ReadyForQuery
message. message.
@ -564,7 +564,7 @@
<listitem> <listitem>
<para> <para>
The backend is ready to copy data from the frontend to a The backend is ready to copy data from the frontend to a
table; see <xref linkend="protocol-copy">. table; see <xref linkend="protocol-copy"/>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -574,7 +574,7 @@
<listitem> <listitem>
<para> <para>
The backend is ready to copy data from a table to the The backend is ready to copy data from a table to the
frontend; see <xref linkend="protocol-copy">. frontend; see <xref linkend="protocol-copy"/>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -654,7 +654,7 @@
normally consists of RowDescription, zero or more normally consists of RowDescription, zero or more
DataRow messages, and then CommandComplete. DataRow messages, and then CommandComplete.
<command>COPY</command> to or from the frontend invokes special protocol <command>COPY</command> to or from the frontend invokes special protocol
as described in <xref linkend="protocol-copy">. as described in <xref linkend="protocol-copy"/>.
All other query types normally produce only All other query types normally produce only
a CommandComplete message. a CommandComplete message.
</para> </para>
@ -691,7 +691,7 @@
<para> <para>
A frontend must be prepared to accept ErrorResponse and A frontend must be prepared to accept ErrorResponse and
NoticeResponse messages whenever it is expecting any other type of NoticeResponse messages whenever it is expecting any other type of
message. See also <xref linkend="protocol-async"> concerning messages message. See also <xref linkend="protocol-async"/> concerning messages
that the backend might generate due to outside events. that the backend might generate due to outside events.
</para> </para>
@ -1198,7 +1198,7 @@ SELCT 1/0;
It is possible for NoticeResponse and ParameterStatus messages to be It is possible for NoticeResponse and ParameterStatus messages to be
interspersed between CopyData messages; frontends must handle these cases, interspersed between CopyData messages; frontends must handle these cases,
and should be prepared for other asynchronous message types as well (see and should be prepared for other asynchronous message types as well (see
<xref linkend="protocol-async">). Otherwise, any message type other than <xref linkend="protocol-async"/>). Otherwise, any message type other than
CopyData or CopyDone may be treated as terminating copy-out mode. CopyData or CopyDone may be treated as terminating copy-out mode.
</para> </para>
@ -1221,7 +1221,7 @@ SELCT 1/0;
until a Sync message is received, and then issue ReadyForQuery and return until a Sync message is received, and then issue ReadyForQuery and return
to normal processing. The frontend should treat receipt of ErrorResponse to normal processing. The frontend should treat receipt of ErrorResponse
as terminating the copy in both directions; no CopyDone should be sent as terminating the copy in both directions; no CopyDone should be sent
in this case. See <xref linkend="protocol-replication"> for more in this case. See <xref linkend="protocol-replication"/> for more
information on the subprotocol transmitted over copy-both mode. information on the subprotocol transmitted over copy-both mode.
</para> </para>
@ -1435,7 +1435,7 @@ SELCT 1/0;
communication security in environments where attackers might be communication security in environments where attackers might be
able to capture the session traffic. For more information on able to capture the session traffic. For more information on
encrypting <productname>PostgreSQL</productname> sessions with encrypting <productname>PostgreSQL</productname> sessions with
<acronym>SSL</acronym>, see <xref linkend="ssl-tcp">. <acronym>SSL</acronym>, see <xref linkend="ssl-tcp"/>.
</para> </para>
<para> <para>
@ -1635,7 +1635,7 @@ of <literal>true</literal> tells the backend to go into walsender mode, wherein
small set of replication commands can be issued instead of SQL statements. Only small set of replication commands can be issued instead of SQL statements. Only
the simple query protocol can be used in walsender mode. the simple query protocol can be used in walsender mode.
Replication commands are logged in the server log when Replication commands are logged in the server log when
<xref linkend="guc-log-replication-commands"> is enabled. <xref linkend="guc-log-replication-commands"/> is enabled.
Passing <literal>database</literal> as the value instructs walsender to connect to Passing <literal>database</literal> as the value instructs walsender to connect to
the database specified in the <literal>dbname</literal> parameter, which will allow the database specified in the <literal>dbname</literal> parameter, which will allow
the connection to be used for logical replication from that database. the connection to be used for logical replication from that database.
@ -1649,8 +1649,8 @@ the connection to be used for logical replication from that database.
psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</programlisting> </programlisting>
However, it is often more useful to use However, it is often more useful to use
<xref linkend="app-pgreceivewal"> (for physical replication) or <xref linkend="app-pgreceivewal"/> (for physical replication) or
<xref linkend="app-pgrecvlogical"> (for logical replication). <xref linkend="app-pgrecvlogical"/> (for logical replication).
</para> </para>
<para> <para>
@ -1728,7 +1728,7 @@ The commands accepted in walsender mode are:
<listitem> <listitem>
<para> <para>
Requests the server to send the current setting of a run-time parameter. Requests the server to send the current setting of a run-time parameter.
This is similar to the SQL command <xref linkend="sql-show">. This is similar to the SQL command <xref linkend="sql-show"/>.
</para> </para>
<variablelist> <variablelist>
@ -1737,7 +1737,7 @@ The commands accepted in walsender mode are:
<listitem> <listitem>
<para> <para>
The name of a run-time parameter. Available parameters are documented The name of a run-time parameter. Available parameters are documented
in <xref linkend="runtime-config">. in <xref linkend="runtime-config"/>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1792,7 +1792,7 @@ The commands accepted in walsender mode are:
<listitem> <listitem>
<para> <para>
Create a physical or logical replication Create a physical or logical replication
slot. See <xref linkend="streaming-replication-slots"> for more about slot. See <xref linkend="streaming-replication-slots"/> for more about
replication slots. replication slots.
</para> </para>
<variablelist> <variablelist>
@ -1801,7 +1801,7 @@ The commands accepted in walsender mode are:
<listitem> <listitem>
<para> <para>
The name of the slot to create. Must be a valid replication slot The name of the slot to create. Must be a valid replication slot
name (see <xref linkend="streaming-replication-slots-manipulation">). name (see <xref linkend="streaming-replication-slots-manipulation"/>).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1811,7 +1811,7 @@ The commands accepted in walsender mode are:
<listitem> <listitem>
<para> <para>
The name of the output plugin used for logical decoding The name of the output plugin used for logical decoding
(see <xref linkend="logicaldecoding-output-plugin">). (see <xref linkend="logicaldecoding-output-plugin"/>).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -2378,7 +2378,7 @@ The commands accepted in walsender mode are:
Sets the label of the backup. If none is specified, a backup label Sets the label of the backup. If none is specified, a backup label
of <literal>base backup</literal> will be used. The quoting rules of <literal>base backup</literal> will be used. The quoting rules
for the label are the same as a standard SQL string with for the label are the same as a standard SQL string with
<xref linkend="guc-standard-conforming-strings"> turned on. <xref linkend="guc-standard-conforming-strings"/> turned on.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -2642,7 +2642,7 @@ The commands accepted in walsender mode are:
<para> <para>
The individual protocol messages are discussed in the following The individual protocol messages are discussed in the following
subsections. Individual messages are described in subsections. Individual messages are described in
<xref linkend="protocol-logicalrep-message-formats">. <xref linkend="protocol-logicalrep-message-formats"/>.
</para> </para>
<para> <para>
@ -4006,7 +4006,7 @@ CopyInResponse (B)
characters, etc). characters, etc).
1 indicates the overall copy format is binary (similar 1 indicates the overall copy format is binary (similar
to DataRow format). to DataRow format).
See <xref linkend="sql-copy"> See <xref linkend="sql-copy"/>
for more information. for more information.
</para> </para>
</listitem> </listitem>
@ -4080,7 +4080,7 @@ CopyOutResponse (B)
is textual (rows separated by newlines, columns is textual (rows separated by newlines, columns
separated by separator characters, etc). 1 indicates separated by separator characters, etc). 1 indicates
the overall copy format is binary (similar to DataRow the overall copy format is binary (similar to DataRow
format). See <xref linkend="sql-copy"> for more information. format). See <xref linkend="sql-copy"/> for more information.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -4153,7 +4153,7 @@ CopyBothResponse (B)
is textual (rows separated by newlines, columns is textual (rows separated by newlines, columns
separated by separator characters, etc). 1 indicates separated by separator characters, etc). 1 indicates
the overall copy format is binary (similar to DataRow the overall copy format is binary (similar to DataRow
format). See <xref linkend="sql-copy"> for more information. format). See <xref linkend="sql-copy"/> for more information.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -4394,7 +4394,7 @@ ErrorResponse (B)
A code identifying the field type; if zero, this is A code identifying the field type; if zero, this is
the message terminator and no string follows. the message terminator and no string follows.
The presently defined field types are listed in The presently defined field types are listed in
<xref linkend="protocol-error-fields">. <xref linkend="protocol-error-fields"/>.
Since more field types might be added in future, Since more field types might be added in future,
frontends should silently ignore fields of unrecognized frontends should silently ignore fields of unrecognized
type. type.
@ -4886,7 +4886,7 @@ NoticeResponse (B)
A code identifying the field type; if zero, this is A code identifying the field type; if zero, this is
the message terminator and no string follows. the message terminator and no string follows.
The presently defined field types are listed in The presently defined field types are listed in
<xref linkend="protocol-error-fields">. <xref linkend="protocol-error-fields"/>.
Since more field types might be added in future, Since more field types might be added in future,
frontends should silently ignore fields of unrecognized frontends should silently ignore fields of unrecognized
type. type.
@ -5757,7 +5757,7 @@ StartupMessage (F)
<literal>true</literal>, <literal>false</literal>, or <literal>true</literal>, <literal>false</literal>, or
<literal>database</literal>, and the default is <literal>database</literal>, and the default is
<literal>false</literal>. See <literal>false</literal>. See
<xref linkend="protocol-replication"> for details. <xref linkend="protocol-replication"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -5919,7 +5919,7 @@ message.
<listitem> <listitem>
<para> <para>
Code: the SQLSTATE code for the error (see <xref Code: the SQLSTATE code for the error (see <xref
linkend="errcodes-appendix">). Not localizable. Always present. linkend="errcodes-appendix"/>). Not localizable. Always present.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -6124,7 +6124,7 @@ message.
<para> <para>
The fields for schema name, table name, column name, data type name, and The fields for schema name, table name, column name, data type name, and
constraint name are supplied only for a limited number of error types; constraint name are supplied only for a limited number of error types;
see <xref linkend="errcodes-appendix">. Frontends should not assume that see <xref linkend="errcodes-appendix"/>. Frontends should not assume that
the presence of any of these fields guarantees the presence of another the presence of any of these fields guarantees the presence of another
field. Core error sources observe the interrelationships noted above, but field. Core error sources observe the interrelationships noted above, but
user-defined functions may use these fields in other ways. In the same user-defined functions may use these fields in other ways. In the same
@ -6149,7 +6149,7 @@ not line breaks.
This section describes the detailed format of each logical replication message. This section describes the detailed format of each logical replication message.
These messages are returned either by the replication slot SQL interface or are 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 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"> protocol WAL messages as described in <xref linkend="protocol-replication"/>
and generally obey same message flow as physical replication. and generally obey same message flow as physical replication.
</para> </para>

56
doc/src/sgml/queries.sgml
View File

@ -24,7 +24,7 @@
<para> <para>
The process of retrieving or the command to retrieve data from a The process of retrieving or the command to retrieve data from a
database is called a <firstterm>query</firstterm>. In SQL the database is called a <firstterm>query</firstterm>. In SQL the
<xref linkend="sql-select"> command is <xref linkend="sql-select"/> command is
used to specify queries. The general syntax of the used to specify queries. The general syntax of the
<command>SELECT</command> command is <command>SELECT</command> command is
<synopsis> <synopsis>
@ -59,7 +59,7 @@ SELECT a, b + c FROM table1;
</programlisting> </programlisting>
(assuming that <literal>b</literal> and <literal>c</literal> are of a numerical (assuming that <literal>b</literal> and <literal>c</literal> are of a numerical
data type). data type).
See <xref linkend="queries-select-lists"> for more details. See <xref linkend="queries-select-lists"/> for more details.
</para> </para>
<para> <para>
@ -110,7 +110,7 @@ SELECT random();
<title>The <literal>FROM</literal> Clause</title> <title>The <literal>FROM</literal> Clause</title>
<para> <para>
The <xref linkend="sql-from" endterm="sql-from-title"> derives a The <xref linkend="sql-from" endterm="sql-from-title"/> derives a
table from one or more other tables given in a comma-separated table from one or more other tables given in a comma-separated
table reference list. table reference list.
<synopsis> <synopsis>
@ -589,7 +589,7 @@ SELECT * FROM my_table AS m WHERE my_table.a &gt; 5; -- wrong
SELECT * FROM people AS mother JOIN people AS child ON mother.id = child.mother_id; SELECT * FROM people AS mother JOIN people AS child ON mother.id = child.mother_id;
</programlisting> </programlisting>
Additionally, an alias is required if the table reference is a Additionally, an alias is required if the table reference is a
subquery (see <xref linkend="queries-subqueries">). subquery (see <xref linkend="queries-subqueries"/>).
</para> </para>
<para> <para>
@ -640,7 +640,7 @@ SELECT a.* FROM (my_table AS a JOIN your_table AS b ON ...) AS c
<para> <para>
Subqueries specifying a derived table must be enclosed in Subqueries specifying a derived table must be enclosed in
parentheses and <emphasis>must</emphasis> be assigned a table parentheses and <emphasis>must</emphasis> be assigned a table
alias name (as in <xref linkend="queries-table-aliases">). For alias name (as in <xref linkend="queries-table-aliases"/>). For
example: example:
<programlisting> <programlisting>
FROM (SELECT * FROM table1) AS alias_name FROM (SELECT * FROM table1) AS alias_name
@ -662,7 +662,7 @@ FROM (VALUES ('anne', 'smith'), ('bob', 'jones'), ('joe', 'blow'))
</programlisting> </programlisting>
Again, a table alias is required. Assigning alias names to the columns Again, a table alias is required. Assigning alias names to the columns
of the <command>VALUES</command> list is optional, but is good practice. of the <command>VALUES</command> list is optional, but is good practice.
For more information see <xref linkend="queries-values">. For more information see <xref linkend="queries-values"/>.
</para> </para>
</sect3> </sect3>
@ -713,7 +713,7 @@ ROWS FROM( <replaceable>function_call</replaceable> <optional>, ... </optional>
The special table function <literal>UNNEST</literal> may be called with The special table function <literal>UNNEST</literal> may be called with
any number of array parameters, and it returns a corresponding number of any number of array parameters, and it returns a corresponding number of
columns, as if <literal>UNNEST</literal> columns, as if <literal>UNNEST</literal>
(<xref linkend="functions-array">) had been called on each parameter (<xref linkend="functions-array"/>) had been called on each parameter
separately and combined using the <literal>ROWS FROM</literal> construct. separately and combined using the <literal>ROWS FROM</literal> construct.
</para> </para>
@ -795,8 +795,8 @@ SELECT *
AS t1(proname name, prosrc text) AS t1(proname name, prosrc text)
WHERE proname LIKE 'bytea%'; WHERE proname LIKE 'bytea%';
</programlisting> </programlisting>
The <xref linkend="contrib-dblink-function"> function The <xref linkend="contrib-dblink-function"/> function
(part of the <xref linkend="dblink"> module) executes (part of the <xref linkend="dblink"/> module) executes
a remote query. It is declared to return a remote query. It is declared to return
<type>record</type> since it might be used for any kind of query. <type>record</type> since it might be used for any kind of query.
The actual column set must be specified in the calling query so The actual column set must be specified in the calling query so
@ -908,12 +908,12 @@ WHERE pname IS NULL;
<para> <para>
The syntax of the <xref linkend="sql-where" The syntax of the <xref linkend="sql-where"
endterm="sql-where-title"> is endterm="sql-where-title"/> is
<synopsis> <synopsis>
WHERE <replaceable>search_condition</replaceable> WHERE <replaceable>search_condition</replaceable>
</synopsis> </synopsis>
where <replaceable>search_condition</replaceable> is any value where <replaceable>search_condition</replaceable> is any value
expression (see <xref linkend="sql-expressions">) that expression (see <xref linkend="sql-expressions"/>) that
returns a value of type <type>boolean</type>. returns a value of type <type>boolean</type>.
</para> </para>
@ -1014,7 +1014,7 @@ SELECT <replaceable>select_list</replaceable>
</synopsis> </synopsis>
<para> <para>
The <xref linkend="sql-groupby" endterm="sql-groupby-title"> is The <xref linkend="sql-groupby" endterm="sql-groupby-title"/> is
used to group together those rows in a table that have the same used to group together those rows in a table that have the same
values in all the columns listed. The order in which the columns values in all the columns listed. The order in which the columns
are listed does not matter. The effect is to combine each set are listed does not matter. The effect is to combine each set
@ -1066,7 +1066,7 @@ SELECT <replaceable>select_list</replaceable>
Here <literal>sum</literal> is an aggregate function that Here <literal>sum</literal> is an aggregate function that
computes a single value over the entire group. More information computes a single value over the entire group. More information
about the available aggregate functions can be found in <xref about the available aggregate functions can be found in <xref
linkend="functions-aggregate">. linkend="functions-aggregate"/>.
</para> </para>
<tip> <tip>
@ -1074,7 +1074,7 @@ SELECT <replaceable>select_list</replaceable>
Grouping without aggregate expressions effectively calculates the Grouping without aggregate expressions effectively calculates the
set of distinct values in a column. This can also be achieved set of distinct values in a column. This can also be achieved
using the <literal>DISTINCT</literal> clause (see <xref using the <literal>DISTINCT</literal> clause (see <xref
linkend="queries-distinct">). linkend="queries-distinct"/>).
</para> </para>
</tip> </tip>
@ -1236,7 +1236,7 @@ SELECT product_id, p.name, (sum(s.units) * (p.price - p.cost)) AS profit
References to the grouping columns or expressions are replaced References to the grouping columns or expressions are replaced
by null values in result rows for grouping sets in which those by null values in result rows for grouping sets in which those
columns do not appear. To distinguish which grouping a particular output columns do not appear. To distinguish which grouping a particular output
row resulted from, see <xref linkend="functions-grouping-table">. row resulted from, see <xref linkend="functions-grouping-table"/>.
</para> </para>
<para> <para>
@ -1366,9 +1366,9 @@ GROUP BY GROUPING SETS (
<para> <para>
If the query contains any window functions (see If the query contains any window functions (see
<xref linkend="tutorial-window">, <xref linkend="tutorial-window"/>,
<xref linkend="functions-window"> and <xref linkend="functions-window"/> and
<xref linkend="syntax-window-functions">), these functions are evaluated <xref linkend="syntax-window-functions"/>), these functions are evaluated
after any grouping, aggregation, and <literal>HAVING</literal> filtering is after any grouping, aggregation, and <literal>HAVING</literal> filtering is
performed. That is, if the query uses any aggregates, <literal>GROUP performed. That is, if the query uses any aggregates, <literal>GROUP
BY</literal>, or <literal>HAVING</literal>, then the rows seen by the window functions BY</literal>, or <literal>HAVING</literal>, then the rows seen by the window functions
@ -1430,7 +1430,7 @@ GROUP BY GROUPING SETS (
The simplest kind of select list is <literal>*</literal> which The simplest kind of select list is <literal>*</literal> which
emits all columns that the table expression produces. Otherwise, emits all columns that the table expression produces. Otherwise,
a select list is a comma-separated list of value expressions (as a select list is a comma-separated list of value expressions (as
defined in <xref linkend="sql-expressions">). For instance, it defined in <xref linkend="sql-expressions"/>). For instance, it
could be a list of column names: could be a list of column names:
<programlisting> <programlisting>
SELECT a, b, c FROM ... SELECT a, b, c FROM ...
@ -1438,7 +1438,7 @@ SELECT a, b, c FROM ...
The columns names <literal>a</literal>, <literal>b</literal>, and <literal>c</literal> The columns names <literal>a</literal>, <literal>b</literal>, and <literal>c</literal>
are either the actual names of the columns of tables referenced are either the actual names of the columns of tables referenced
in the <literal>FROM</literal> clause, or the aliases given to them as in the <literal>FROM</literal> clause, or the aliases given to them as
explained in <xref linkend="queries-table-aliases">. The name explained in <xref linkend="queries-table-aliases"/>. The name
space available in the select list is the same as in the space available in the select list is the same as in the
<literal>WHERE</literal> clause, unless grouping is used, in which case <literal>WHERE</literal> clause, unless grouping is used, in which case
it is the same as in the <literal>HAVING</literal> clause. it is the same as in the <literal>HAVING</literal> clause.
@ -1455,7 +1455,7 @@ SELECT tbl1.a, tbl2.a, tbl1.b FROM ...
<programlisting> <programlisting>
SELECT tbl1.*, tbl2.a FROM ... SELECT tbl1.*, tbl2.a FROM ...
</programlisting> </programlisting>
See <xref linkend="rowtypes-usage"> for more about See <xref linkend="rowtypes-usage"/> for more about
the <replaceable>table_name</replaceable><literal>.*</literal> notation. the <replaceable>table_name</replaceable><literal>.*</literal> notation.
</para> </para>
@ -1499,7 +1499,7 @@ SELECT a AS value, b + c AS sum FROM ...
The <literal>AS</literal> keyword is optional, but only if the new column The <literal>AS</literal> keyword is optional, but only if the new column
name does not match any name does not match any
<productname>PostgreSQL</productname> keyword (see <xref <productname>PostgreSQL</productname> keyword (see <xref
linkend="sql-keywords-appendix">). To avoid an accidental match to linkend="sql-keywords-appendix"/>). To avoid an accidental match to
a keyword, you can double-quote the column name. For example, a keyword, you can double-quote the column name. For example,
<literal>VALUE</literal> is a keyword, so this does not work: <literal>VALUE</literal> is a keyword, so this does not work:
<programlisting> <programlisting>
@ -1518,7 +1518,7 @@ SELECT a "value", b + c AS sum FROM ...
<para> <para>
The naming of output columns here is different from that done in The naming of output columns here is different from that done in
the <literal>FROM</literal> clause (see <xref the <literal>FROM</literal> clause (see <xref
linkend="queries-table-aliases">). It is possible linkend="queries-table-aliases"/>). It is possible
to rename the same column twice, but the name assigned in to rename the same column twice, but the name assigned in
the select list is the one that will be passed on. the select list is the one that will be passed on.
</para> </para>
@ -1663,7 +1663,7 @@ SELECT DISTINCT ON (<replaceable>expression</replaceable> <optional>, <replaceab
queries, the two queries must be <quote>union compatible</quote>, queries, the two queries must be <quote>union compatible</quote>,
which means that they return the same number of columns and which means that they return the same number of columns and
the corresponding columns have compatible data types, as the corresponding columns have compatible data types, as
described in <xref linkend="typeconv-union-case">. described in <xref linkend="typeconv-union-case"/>.
</para> </para>
</sect1> </sect1>
@ -1861,7 +1861,7 @@ VALUES ( <replaceable class="parameter">expression</replaceable> [, ...] ) [, ..
of columns in the table), and corresponding entries in each list must of columns in the table), and corresponding entries in each list must
have compatible data types. The actual data type assigned to each column have compatible data types. The actual data type assigned to each column
of the result is determined using the same rules as for <literal>UNION</literal> of the result is determined using the same rules as for <literal>UNION</literal>
(see <xref linkend="typeconv-union-case">). (see <xref linkend="typeconv-union-case"/>).
</para> </para>
<para> <para>
@ -1912,7 +1912,7 @@ SELECT <replaceable>select_list</replaceable> FROM <replaceable>table_expression
</para> </para>
<para> <para>
For more information see <xref linkend="sql-values">. For more information see <xref linkend="sql-values"/>.
</para> </para>
</sect1> </sect1>
@ -2261,7 +2261,7 @@ SELECT * FROM moved_rows;
<para> <para>
Data-modifying statements in <literal>WITH</literal> usually have Data-modifying statements in <literal>WITH</literal> usually have
<literal>RETURNING</literal> clauses (see <xref linkend="dml-returning">), <literal>RETURNING</literal> clauses (see <xref linkend="dml-returning"/>),
as shown in the example above. as shown in the example above.
It is the output of the <literal>RETURNING</literal> clause, <emphasis>not</emphasis> the It is the output of the <literal>RETURNING</literal> clause, <emphasis>not</emphasis> the
target table of the data-modifying statement, that forms the temporary target table of the data-modifying statement, that forms the temporary
@ -2317,7 +2317,7 @@ DELETE FROM parts
each other and with the main query. Therefore, when using data-modifying each other and with the main query. Therefore, when using data-modifying
statements in <literal>WITH</literal>, the order in which the specified updates statements in <literal>WITH</literal>, the order in which the specified updates
actually happen is unpredictable. All the statements are executed with actually happen is unpredictable. All the statements are executed with
the same <firstterm>snapshot</firstterm> (see <xref linkend="mvcc">), so they the same <firstterm>snapshot</firstterm> (see <xref linkend="mvcc"/>), so they
cannot <quote>see</quote> one another's effects on the target tables. This cannot <quote>see</quote> one another's effects on the target tables. This
alleviates the effects of the unpredictability of the actual order of row alleviates the effects of the unpredictability of the actual order of row
updates, and means that <literal>RETURNING</literal> data is the only way to updates, and means that <literal>RETURNING</literal> data is the only way to

8
doc/src/sgml/query.sgml
View File

@ -12,7 +12,7 @@
tutorial is only intended to give you an introduction and is in no tutorial is only intended to give you an introduction and is in no
way a complete tutorial on <acronym>SQL</acronym>. Numerous books way a complete tutorial on <acronym>SQL</acronym>. Numerous books
have been written on <acronym>SQL</acronym>, including <xref have been written on <acronym>SQL</acronym>, including <xref
linkend="melt93"> and <xref linkend="date97">. linkend="melt93"/> and <xref linkend="date97"/>.
You should be aware that some <productname>PostgreSQL</productname> You should be aware that some <productname>PostgreSQL</productname>
language features are extensions to the standard. language features are extensions to the standard.
</para> </para>
@ -267,7 +267,7 @@ COPY weather FROM '/home/user/weather.txt';
where the file name for the source file must be available on the where the file name for the source file must be available on the
machine running the backend process, not the client, since the backend process machine running the backend process, not the client, since the backend process
reads the file directly. You can read more about the reads the file directly. You can read more about the
<command>COPY</command> command in <xref linkend="sql-copy">. <command>COPY</command> command in <xref linkend="sql-copy"/>.
</para> </para>
</sect1> </sect1>
@ -754,7 +754,7 @@ SELECT city, max(temp_lo)
<programlisting> <programlisting>
SELECT city, max(temp_lo) SELECT city, max(temp_lo)
FROM weather 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 GROUP BY city
HAVING max(temp_lo) &lt; 40; HAVING max(temp_lo) &lt; 40;
</programlisting> </programlisting>
@ -762,7 +762,7 @@ SELECT city, max(temp_lo)
<callout arearefs="co.tutorial-agg-like"> <callout arearefs="co.tutorial-agg-like">
<para> <para>
The <literal>LIKE</literal> operator does pattern matching and The <literal>LIKE</literal> operator does pattern matching and
is explained in <xref linkend="functions-matching">. is explained in <xref linkend="functions-matching"/>.
</para> </para>
</callout> </callout>
</calloutlist> </calloutlist>

14
doc/src/sgml/rangetypes.sgml
View File

@ -65,7 +65,7 @@
</listitem> </listitem>
</itemizedlist> </itemizedlist>
In addition, you can define your own range types; In addition, you can define your own range types;
see <xref linkend="sql-createtype"> for more information. see <xref linkend="sql-createtype"/> for more information.
</para> </para>
</sect2> </sect2>
@ -94,8 +94,8 @@ SELECT int4range(10, 20) * int4range(15, 25);
SELECT isempty(numrange(1, 5)); SELECT isempty(numrange(1, 5));
</programlisting> </programlisting>
See <xref linkend="range-operators-table"> See <xref linkend="range-operators-table"/>
and <xref linkend="range-functions-table"> for complete lists of and <xref linkend="range-functions-table"/> for complete lists of
operators and functions on range types. operators and functions on range types.
</para> </para>
</sect2> </sect2>
@ -117,7 +117,7 @@ SELECT isempty(numrange(1, 5));
represented by <quote><literal>(</literal></quote>. Likewise, an inclusive upper bound is represented by represented by <quote><literal>(</literal></quote>. Likewise, an inclusive upper bound is represented by
<quote><literal>]</literal></quote>, while an exclusive upper bound is <quote><literal>]</literal></quote>, while an exclusive upper bound is
represented by <quote><literal>)</literal></quote>. represented by <quote><literal>)</literal></quote>.
(See <xref linkend="rangetypes-io"> for more details.) (See <xref linkend="rangetypes-io"/> for more details.)
</para> </para>
<para> <para>
@ -214,7 +214,7 @@ empty
<note> <note>
<para> <para>
These rules are very similar to those for writing field values in These rules are very similar to those for writing field values in
composite-type literals. See <xref linkend="rowtypes-io-syntax"> for composite-type literals. See <xref linkend="rowtypes-io-syntax"/> for
additional commentary. additional commentary.
</para> </para>
</note> </note>
@ -406,7 +406,7 @@ SELECT '[11:10, 23:00]'::timerange;
</programlisting> </programlisting>
<para> <para>
See <xref linkend="sql-createtype"> for more information about creating See <xref linkend="sql-createtype"/> for more information about creating
range types. range types.
</para> </para>
</sect2> </sect2>
@ -435,7 +435,7 @@ CREATE INDEX reservation_idx ON reservation USING GIST (during);
<literal>-|-</literal>, <literal>-|-</literal>,
<literal>&amp;&lt;</literal>, and <literal>&amp;&lt;</literal>, and
<literal>&amp;&gt;</literal> <literal>&amp;&gt;</literal>
(see <xref linkend="range-operators-table"> for more information). (see <xref linkend="range-operators-table"/> for more information).
</para> </para>
<para> <para>

34
doc/src/sgml/recovery-config.sgml
View File

@ -58,7 +58,7 @@
to truncate the archive to just the minimum required to support to truncate the archive to just the minimum required to support
restarting from the current restore. <literal>%r</literal> is typically only restarting from the current restore. <literal>%r</literal> is typically only
used by warm-standby configurations used by warm-standby configurations
(see <xref linkend="warm-standby">). (see <xref linkend="warm-standby"/>).
Write <literal>%%</literal> to embed an actual <literal>%</literal> character. Write <literal>%%</literal> to embed an actual <literal>%</literal> character.
</para> </para>
@ -99,7 +99,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
may be safely removed. may be safely removed.
This information can be used to truncate the archive to just the This information can be used to truncate the archive to just the
minimum required to support restart from the current restore. minimum required to support restart from the current restore.
The <xref linkend="pgarchivecleanup"> module The <xref linkend="pgarchivecleanup"/> module
is often used in <varname>archive_cleanup_command</varname> for is often used in <varname>archive_cleanup_command</varname> for
single-standby configurations, for example: single-standby configurations, for example:
<programlisting>archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r'</programlisting> <programlisting>archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r'</programlisting>
@ -107,7 +107,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
same archive directory, you will need to ensure that you do not delete same archive directory, you will need to ensure that you do not delete
WAL files until they are no longer needed by any of the servers. WAL files until they are no longer needed by any of the servers.
<varname>archive_cleanup_command</varname> would typically be used in a <varname>archive_cleanup_command</varname> would typically be used in a
warm-standby configuration (see <xref linkend="warm-standby">). warm-standby configuration (see <xref linkend="warm-standby"/>).
Write <literal>%%</literal> to embed an actual <literal>%</literal> character in the Write <literal>%%</literal> to embed an actual <literal>%</literal> character in the
command. command.
</para> </para>
@ -133,7 +133,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
<varname>recovery_end_command</varname> is to provide a mechanism for cleanup <varname>recovery_end_command</varname> is to provide a mechanism for cleanup
following replication or recovery. following replication or recovery.
Any <literal>%r</literal> is replaced by the name of the file containing the Any <literal>%r</literal> is replaced by the name of the file containing the
last valid restart point, like in <xref linkend="archive-cleanup-command">. last valid restart point, like in <xref linkend="archive-cleanup-command"/>.
</para> </para>
<para> <para>
If the command returns a nonzero exit status then a warning log If the command returns a nonzero exit status then a warning log
@ -209,7 +209,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
This parameter specifies the time stamp up to which recovery This parameter specifies the time stamp up to which recovery
will proceed. will proceed.
The precise stopping point is also influenced by The precise stopping point is also influenced by
<xref linkend="recovery-target-inclusive">. <xref linkend="recovery-target-inclusive"/>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -229,7 +229,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
The transactions that will be recovered are those that committed The transactions that will be recovered are those that committed
before (and optionally including) the specified one. before (and optionally including) the specified one.
The precise stopping point is also influenced by The precise stopping point is also influenced by
<xref linkend="recovery-target-inclusive">. <xref linkend="recovery-target-inclusive"/>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -244,7 +244,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
<para> <para>
This parameter specifies the LSN of the write-ahead log location up This parameter specifies the LSN of the write-ahead log location up
to which recovery will proceed. The precise stopping point is also to which recovery will proceed. The precise stopping point is also
influenced by <xref linkend="recovery-target-inclusive">. This influenced by <xref linkend="recovery-target-inclusive"/>. This
parameter is parsed using the system data type parameter is parsed using the system data type
<link linkend="datatype-pg-lsn"><type>pg_lsn</type></link>. <link linkend="datatype-pg-lsn"><type>pg_lsn</type></link>.
</para> </para>
@ -270,9 +270,9 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
Specifies whether to stop just after the specified recovery target Specifies whether to stop just after the specified recovery target
(<literal>true</literal>), or just before the recovery target (<literal>true</literal>), or just before the recovery target
(<literal>false</literal>). (<literal>false</literal>).
Applies when <xref linkend="recovery-target-lsn">, Applies when <xref linkend="recovery-target-lsn"/>,
<xref linkend="recovery-target-time">, or <xref linkend="recovery-target-time"/>, or
<xref linkend="recovery-target-xid"> is specified. <xref linkend="recovery-target-xid"/> is specified.
This setting controls whether transactions This setting controls whether transactions
having exactly the target WAL location (LSN), commit time, or transaction ID, respectively, will having exactly the target WAL location (LSN), commit time, or transaction ID, respectively, will
be included in the recovery. Default is <literal>true</literal>. be included in the recovery. Default is <literal>true</literal>.
@ -296,7 +296,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
a standby server. Other than that you only need to set this parameter a standby server. Other than that you only need to set this parameter
in complex re-recovery situations, where you need to return to in complex re-recovery situations, where you need to return to
a state that itself was reached after a point-in-time recovery. a state that itself was reached after a point-in-time recovery.
See <xref linkend="backup-timelines"> for discussion. See <xref linkend="backup-timelines"/> for discussion.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -323,7 +323,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
is the most desirable point for recovery. is the most desirable point for recovery.
The paused state can be resumed by The paused state can be resumed by
using <function>pg_wal_replay_resume()</function> (see using <function>pg_wal_replay_resume()</function> (see
<xref linkend="functions-recovery-control-table">), which then <xref linkend="functions-recovery-control-table"/>), which then
causes recovery to end. If this recovery target is not the causes recovery to end. If this recovery target is not the
desired stopping point, then shut down the server, change the desired stopping point, then shut down the server, change the
recovery target settings to a later target and restart to recovery target settings to a later target and restart to
@ -344,7 +344,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
</para> </para>
<para> <para>
This setting has no effect if no recovery target is set. This setting has no effect if no recovery target is set.
If <xref linkend="guc-hot-standby"> is not enabled, a setting of If <xref linkend="guc-hot-standby"/> is not enabled, a setting of
<literal>pause</literal> will act the same as <literal>shutdown</literal>. <literal>pause</literal> will act the same as <literal>shutdown</literal>.
</para> </para>
</listitem> </listitem>
@ -386,9 +386,9 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
<para> <para>
Specifies a connection string to be used for the standby server Specifies a connection string to be used for the standby server
to connect with the primary. This string is in the format to connect with the primary. This string is in the format
described in <xref linkend="libpq-connstring">. If any option is described in <xref linkend="libpq-connstring"/>. If any option is
unspecified in this string, then the corresponding environment unspecified in this string, then the corresponding environment
variable (see <xref linkend="libpq-envars">) is checked. If the variable (see <xref linkend="libpq-envars"/>) is checked. If the
environment variable is not set either, then environment variable is not set either, then
defaults are used. defaults are used.
</para> </para>
@ -398,7 +398,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
the same as the standby server's default. the same as the standby server's default.
Also specify a user name corresponding to a suitably-privileged role Also specify a user name corresponding to a suitably-privileged role
on the primary (see on the primary (see
<xref linkend="streaming-replication-authentication">). <xref linkend="streaming-replication-authentication"/>).
A password needs to be provided too, if the primary demands password A password needs to be provided too, if the primary demands password
authentication. It can be provided in the authentication. It can be provided in the
<varname>primary_conninfo</varname> string, or in a separate <varname>primary_conninfo</varname> string, or in a separate
@ -423,7 +423,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
Optionally specifies an existing replication slot to be used when Optionally specifies an existing replication slot to be used when
connecting to the primary via streaming replication to control connecting to the primary via streaming replication to control
resource removal on the upstream node resource removal on the upstream node
(see <xref linkend="streaming-replication-slots">). (see <xref linkend="streaming-replication-slots"/>).
This setting has no effect if <varname>primary_conninfo</varname> is not This setting has no effect if <varname>primary_conninfo</varname> is not
set. set.
</para> </para>

10
doc/src/sgml/ref/abort.sgml
View File

@ -33,7 +33,7 @@ ABORT [ WORK | TRANSACTION ]
all the updates made by the transaction to be discarded. all the updates made by the transaction to be discarded.
This command is identical This command is identical
in behavior to the standard <acronym>SQL</acronym> command in behavior to the standard <acronym>SQL</acronym> command
<xref linkend="sql-rollback">, <xref linkend="sql-rollback"/>,
and is present only for historical reasons. and is present only for historical reasons.
</para> </para>
</refsect1> </refsect1>
@ -58,7 +58,7 @@ ABORT [ WORK | TRANSACTION ]
<title>Notes</title> <title>Notes</title>
<para> <para>
Use <xref linkend="sql-commit"> to Use <xref linkend="sql-commit"/> to
successfully terminate a transaction. successfully terminate a transaction.
</para> </para>
@ -92,9 +92,9 @@ ABORT;
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="sql-begin"></member> <member><xref linkend="sql-begin"/></member>
<member><xref linkend="sql-commit"></member> <member><xref linkend="sql-commit"/></member>
<member><xref linkend="sql-rollback"></member> <member><xref linkend="sql-rollback"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>

6
doc/src/sgml/ref/alter_aggregate.sgml
View File

@ -142,7 +142,7 @@ ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>aggregate_signatu
The recommended syntax for referencing an ordered-set aggregate The recommended syntax for referencing an ordered-set aggregate
is to write <literal>ORDER BY</literal> between the direct and aggregated is to write <literal>ORDER BY</literal> between the direct and aggregated
argument specifications, in the same style as in argument specifications, in the same style as in
<xref linkend="sql-createaggregate">. However, it will also work to <xref linkend="sql-createaggregate"/>. However, it will also work to
omit <literal>ORDER BY</literal> and just run the direct and aggregated omit <literal>ORDER BY</literal> and just run the direct and aggregated
argument specifications into a single list. In this abbreviated form, argument specifications into a single list. In this abbreviated form,
if <literal>VARIADIC "any"</literal> was used in both the direct and if <literal>VARIADIC "any"</literal> was used in both the direct and
@ -195,8 +195,8 @@ ALTER AGGREGATE mypercentile(float8, integer) SET SCHEMA myschema;
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="sql-createaggregate"></member> <member><xref linkend="sql-createaggregate"/></member>
<member><xref linkend="sql-dropaggregate"></member> <member><xref linkend="sql-dropaggregate"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>

6
doc/src/sgml/ref/alter_collation.sgml
View File

@ -94,7 +94,7 @@ ALTER COLLATION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_sche
<para> <para>
Update the collation's version. Update the collation's version.
See <xref linkend="sql-altercollation-notes" See <xref linkend="sql-altercollation-notes"
endterm="sql-altercollation-notes-title"> below. endterm="sql-altercollation-notes-title"/> below.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -176,8 +176,8 @@ ALTER COLLATION "en_US" OWNER TO joe;
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="sql-createcollation"></member> <member><xref linkend="sql-createcollation"/></member>
<member><xref linkend="sql-dropcollation"></member> <member><xref linkend="sql-dropcollation"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>

4
doc/src/sgml/ref/alter_conversion.sgml
View File

@ -120,8 +120,8 @@ ALTER CONVERSION iso_8859_1_to_utf8 OWNER TO joe;
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="sql-createconversion"></member> <member><xref linkend="sql-createconversion"/></member>
<member><xref linkend="sql-dropconversion"></member> <member><xref linkend="sql-dropconversion"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>

12
doc/src/sgml/ref/alter_database.sgml
View File

@ -188,7 +188,7 @@ ALTER DATABASE <replaceable class="parameter">name</replaceable> RESET ALL
</para> </para>
<para> <para>
See <xref linkend="sql-set"> and <xref linkend="runtime-config"> See <xref linkend="sql-set"/> and <xref linkend="runtime-config"/>
for more information about allowed parameter names for more information about allowed parameter names
and values. and values.
</para> </para>
@ -203,7 +203,7 @@ ALTER DATABASE <replaceable class="parameter">name</replaceable> RESET ALL
<para> <para>
It is also possible to tie a session default to a specific role It is also possible to tie a session default to a specific role
rather than to a database; see rather than to a database; see
<xref linkend="sql-alterrole">. <xref linkend="sql-alterrole"/>.
Role-specific settings override database-specific Role-specific settings override database-specific
ones if there is a conflict. ones if there is a conflict.
</para> </para>
@ -234,10 +234,10 @@ ALTER DATABASE test SET enable_indexscan TO off;
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="sql-createdatabase"></member> <member><xref linkend="sql-createdatabase"/></member>
<member><xref linkend="sql-dropdatabase"></member> <member><xref linkend="sql-dropdatabase"/></member>
<member><xref linkend="sql-set"></member> <member><xref linkend="sql-set"/></member>
<member><xref linkend="sql-createtablespace"></member> <member><xref linkend="sql-createtablespace"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>
</refentry> </refentry>

14
doc/src/sgml/ref/alter_default_privileges.sgml
View File

@ -106,7 +106,7 @@ REVOKE [ GRANT OPTION FOR ]
</para> </para>
<para> <para>
As explained under <xref linkend="sql-grant">, As explained under <xref linkend="sql-grant"/>,
the default privileges for any object type normally grant all grantable the default privileges for any object type normally grant all grantable
permissions to the object owner, and may grant some privileges to permissions to the object owner, and may grant some privileges to
<literal>PUBLIC</literal> as well. However, this behavior can be changed by <literal>PUBLIC</literal> as well. However, this behavior can be changed by
@ -150,8 +150,8 @@ REVOKE [ GRANT OPTION FOR ]
This parameter, and all the other parameters in This parameter, and all the other parameters in
<replaceable class="parameter">abbreviated_grant_or_revoke</replaceable>, <replaceable class="parameter">abbreviated_grant_or_revoke</replaceable>,
act as described under act as described under
<xref linkend="sql-grant"> or <xref linkend="sql-grant"/> or
<xref linkend="sql-revoke">, <xref linkend="sql-revoke"/>,
except that one is setting permissions for a whole class of objects except that one is setting permissions for a whole class of objects
rather than specific named objects. rather than specific named objects.
</para> </para>
@ -165,11 +165,11 @@ REVOKE [ GRANT OPTION FOR ]
<title>Notes</title> <title>Notes</title>
<para> <para>
Use <xref linkend="app-psql">'s <command>\ddp</command> command Use <xref linkend="app-psql"/>'s <command>\ddp</command> command
to obtain information about existing assignments of default privileges. to obtain information about existing assignments of default privileges.
The meaning of the privilege values is the same as explained for The meaning of the privilege values is the same as explained for
<command>\dp</command> under <command>\dp</command> under
<xref linkend="sql-grant">. <xref linkend="sql-grant"/>.
</para> </para>
<para> <para>
@ -226,8 +226,8 @@ ALTER DEFAULT PRIVILEGES FOR ROLE admin REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC;
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="sql-grant"></member> <member><xref linkend="sql-grant"/></member>
<member><xref linkend="sql-revoke"></member> <member><xref linkend="sql-revoke"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>

8
doc/src/sgml/ref/alter_domain.sgml
View File

@ -80,7 +80,7 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable>
<listitem> <listitem>
<para> <para>
This form adds a new constraint to a domain using the same syntax as This form adds a new constraint to a domain using the same syntax as
<xref linkend="sql-createdomain">. <xref linkend="sql-createdomain"/>.
When a new constraint is added to a domain, all columns using that When a new constraint is added to a domain, all columns using that
domain will be checked against the newly added constraint. These domain will be checked against the newly added constraint. These
checks can be suppressed by adding the new constraint using the checks can be suppressed by adding the new constraint using the
@ -214,7 +214,7 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable>
<para> <para>
Automatically drop objects that depend on the constraint, Automatically drop objects that depend on the constraint,
and in turn all objects that depend on those objects and in turn all objects that depend on those objects
(see <xref linkend="ddl-depend">). (see <xref linkend="ddl-depend"/>).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -342,8 +342,8 @@ ALTER DOMAIN zipcode SET SCHEMA customers;
<title>See Also</title> <title>See Also</title>
<simplelist type="inline"> <simplelist type="inline">
<member><xref linkend="sql-createdomain"></member> <member><xref linkend="sql-createdomain"/></member>
<member><xref linkend="sql-dropdomain"></member> <member><xref linkend="sql-dropdomain"/></member>
</simplelist> </simplelist>
</refsect1> </refsect1>

Some files were not shown because too many files have changed in this diff Show More