From 3c49c6facb22cdea979f5d1465ba53f972d32163 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Thu, 23 Nov 2017 09:39:47 -0500 Subject: [PATCH] Convert documentation to DocBook XML MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Since some preparation work had already been done, the only source changes left were changing empty-element tags like to , 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 --- config/docbook.m4 | 22 +- configure | 158 +----- configure.in | 4 +- doc/src/sgml/Makefile | 93 +--- doc/src/sgml/adminpack.sgml | 14 +- doc/src/sgml/advanced.sgml | 22 +- doc/src/sgml/amcheck.sgml | 8 +- doc/src/sgml/arch-dev.sgml | 14 +- doc/src/sgml/array.sgml | 18 +- doc/src/sgml/auth-delay.sgml | 2 +- doc/src/sgml/auto-explain.sgml | 6 +- doc/src/sgml/backup.sgml | 82 +-- doc/src/sgml/bgworker.sgml | 2 +- doc/src/sgml/brin.sgml | 8 +- doc/src/sgml/catalogs.sgml | 202 +++---- doc/src/sgml/charset.sgml | 36 +- doc/src/sgml/client-auth.sgml | 88 +-- doc/src/sgml/config.sgml | 362 ++++++------ doc/src/sgml/contrib.sgml | 18 +- doc/src/sgml/cube.sgml | 6 +- doc/src/sgml/custom-scan.sgml | 2 +- doc/src/sgml/datatype.sgml | 176 +++--- doc/src/sgml/datetime.sgml | 8 +- doc/src/sgml/dblink.sgml | 10 +- doc/src/sgml/ddl.sgml | 126 ++--- doc/src/sgml/dfunc.sgml | 2 +- doc/src/sgml/dict-int.sgml | 2 +- doc/src/sgml/dict-xsyn.sgml | 2 +- doc/src/sgml/diskusage.sgml | 10 +- doc/src/sgml/dml.sgml | 24 +- doc/src/sgml/docguide.sgml | 217 +------- doc/src/sgml/earthdistance.sgml | 4 +- doc/src/sgml/ecpg.sgml | 192 +++---- doc/src/sgml/errcodes.sgml | 8 +- doc/src/sgml/event-trigger.sgml | 18 +- doc/src/sgml/extend.sgml | 56 +- doc/src/sgml/external-projects.sgml | 6 +- doc/src/sgml/fdwhandler.sgml | 40 +- doc/src/sgml/file-fdw.sgml | 2 +- doc/src/sgml/func.sgml | 520 +++++++++--------- doc/src/sgml/geqo.sgml | 6 +- doc/src/sgml/gin.sgml | 24 +- doc/src/sgml/gist.sgml | 6 +- doc/src/sgml/high-availability.sgml | 154 +++--- doc/src/sgml/history.sgml | 16 +- doc/src/sgml/hstore.sgml | 8 +- doc/src/sgml/indexam.sgml | 26 +- doc/src/sgml/indices.sgml | 72 +-- doc/src/sgml/information_schema.sgml | 28 +- doc/src/sgml/install-windows.sgml | 6 +- doc/src/sgml/installation.sgml | 50 +- doc/src/sgml/intarray.sgml | 4 +- doc/src/sgml/intro.sgml | 14 +- doc/src/sgml/isn.sgml | 4 +- doc/src/sgml/json.sgml | 12 +- doc/src/sgml/keywords.sgml | 8 +- doc/src/sgml/libpq.sgml | 156 +++--- doc/src/sgml/lo.sgml | 2 +- doc/src/sgml/lobj.sgml | 14 +- doc/src/sgml/logical-replication.sgml | 28 +- doc/src/sgml/logicaldecoding.sgml | 44 +- doc/src/sgml/ltree.sgml | 6 +- doc/src/sgml/maintenance.sgml | 80 +-- doc/src/sgml/manage-ag.sgml | 38 +- doc/src/sgml/monitoring.sgml | 108 ++-- doc/src/sgml/mvcc.sgml | 66 +-- doc/src/sgml/nls.sgml | 2 +- doc/src/sgml/oid2name.sgml | 2 +- doc/src/sgml/parallel.sgml | 34 +- doc/src/sgml/passwordcheck.sgml | 8 +- doc/src/sgml/perform.sgml | 68 +-- doc/src/sgml/pgbuffercache.sgml | 2 +- doc/src/sgml/pgcrypto.sgml | 8 +- doc/src/sgml/pgprewarm.sgml | 2 +- doc/src/sgml/pgrowlocks.sgml | 2 +- doc/src/sgml/pgstandby.sgml | 8 +- doc/src/sgml/pgstatstatements.sgml | 8 +- doc/src/sgml/pgstattuple.sgml | 4 +- doc/src/sgml/pgtrgm.sgml | 4 +- doc/src/sgml/planstats.sgml | 6 +- doc/src/sgml/plhandler.sgml | 14 +- doc/src/sgml/plperl.sgml | 22 +- doc/src/sgml/plpgsql.sgml | 166 +++--- doc/src/sgml/plpython.sgml | 30 +- doc/src/sgml/pltcl.sgml | 16 +- doc/src/sgml/postgres-fdw.sgml | 40 +- doc/src/sgml/postgres.sgml | 26 +- doc/src/sgml/problems.sgml | 2 +- doc/src/sgml/protocol.sgml | 60 +- doc/src/sgml/queries.sgml | 56 +- doc/src/sgml/query.sgml | 8 +- doc/src/sgml/rangetypes.sgml | 14 +- doc/src/sgml/recovery-config.sgml | 34 +- doc/src/sgml/ref/abort.sgml | 10 +- doc/src/sgml/ref/alter_aggregate.sgml | 6 +- doc/src/sgml/ref/alter_collation.sgml | 6 +- doc/src/sgml/ref/alter_conversion.sgml | 4 +- doc/src/sgml/ref/alter_database.sgml | 12 +- .../sgml/ref/alter_default_privileges.sgml | 14 +- doc/src/sgml/ref/alter_domain.sgml | 8 +- doc/src/sgml/ref/alter_event_trigger.sgml | 6 +- doc/src/sgml/ref/alter_extension.sgml | 6 +- .../sgml/ref/alter_foreign_data_wrapper.sgml | 4 +- doc/src/sgml/ref/alter_foreign_table.sgml | 28 +- doc/src/sgml/ref/alter_function.sgml | 22 +- doc/src/sgml/ref/alter_group.sgml | 12 +- doc/src/sgml/ref/alter_index.sgml | 18 +- doc/src/sgml/ref/alter_language.sgml | 4 +- doc/src/sgml/ref/alter_large_object.sgml | 2 +- doc/src/sgml/ref/alter_materialized_view.sgml | 8 +- doc/src/sgml/ref/alter_opclass.sgml | 6 +- doc/src/sgml/ref/alter_operator.sgml | 4 +- doc/src/sgml/ref/alter_opfamily.sgml | 14 +- doc/src/sgml/ref/alter_policy.sgml | 8 +- doc/src/sgml/ref/alter_publication.sgml | 12 +- doc/src/sgml/ref/alter_role.sgml | 44 +- doc/src/sgml/ref/alter_rule.sgml | 4 +- doc/src/sgml/ref/alter_schema.sgml | 4 +- doc/src/sgml/ref/alter_sequence.sgml | 4 +- doc/src/sgml/ref/alter_server.sgml | 4 +- doc/src/sgml/ref/alter_statistics.sgml | 4 +- doc/src/sgml/ref/alter_subscription.sgml | 16 +- doc/src/sgml/ref/alter_system.sgml | 10 +- doc/src/sgml/ref/alter_table.sgml | 56 +- doc/src/sgml/ref/alter_tablespace.sgml | 10 +- doc/src/sgml/ref/alter_trigger.sgml | 4 +- doc/src/sgml/ref/alter_tsconfig.sgml | 4 +- doc/src/sgml/ref/alter_tsdictionary.sgml | 4 +- doc/src/sgml/ref/alter_tsparser.sgml | 4 +- doc/src/sgml/ref/alter_tstemplate.sgml | 4 +- doc/src/sgml/ref/alter_type.sgml | 6 +- doc/src/sgml/ref/alter_user.sgml | 4 +- doc/src/sgml/ref/alter_user_mapping.sgml | 4 +- doc/src/sgml/ref/alter_view.sgml | 4 +- doc/src/sgml/ref/analyze.sgml | 22 +- doc/src/sgml/ref/begin.sgml | 26 +- doc/src/sgml/ref/checkpoint.sgml | 6 +- doc/src/sgml/ref/close.sgml | 8 +- doc/src/sgml/ref/cluster.sgml | 10 +- doc/src/sgml/ref/clusterdb.sgml | 10 +- doc/src/sgml/ref/comment.sgml | 2 +- doc/src/sgml/ref/commit.sgml | 6 +- doc/src/sgml/ref/commit_prepared.sgml | 4 +- doc/src/sgml/ref/copy.sgml | 6 +- doc/src/sgml/ref/create_access_method.sgml | 8 +- doc/src/sgml/ref/create_aggregate.sgml | 20 +- doc/src/sgml/ref/create_cast.sgml | 10 +- doc/src/sgml/ref/create_collation.sgml | 10 +- doc/src/sgml/ref/create_conversion.sgml | 6 +- doc/src/sgml/ref/create_database.sgml | 18 +- doc/src/sgml/ref/create_domain.sgml | 4 +- doc/src/sgml/ref/create_event_trigger.sgml | 12 +- doc/src/sgml/ref/create_extension.sgml | 6 +- .../sgml/ref/create_foreign_data_wrapper.sgml | 10 +- doc/src/sgml/ref/create_foreign_table.sgml | 16 +- doc/src/sgml/ref/create_function.sgml | 36 +- doc/src/sgml/ref/create_group.sgml | 4 +- doc/src/sgml/ref/create_index.sgml | 38 +- doc/src/sgml/ref/create_language.sgml | 20 +- .../sgml/ref/create_materialized_view.sgml | 20 +- doc/src/sgml/ref/create_opclass.sgml | 12 +- doc/src/sgml/ref/create_operator.sgml | 16 +- doc/src/sgml/ref/create_opfamily.sgml | 12 +- doc/src/sgml/ref/create_policy.sgml | 8 +- doc/src/sgml/ref/create_publication.sgml | 6 +- doc/src/sgml/ref/create_role.sgml | 36 +- doc/src/sgml/ref/create_rule.sgml | 10 +- doc/src/sgml/ref/create_schema.sgml | 4 +- doc/src/sgml/ref/create_sequence.sgml | 6 +- doc/src/sgml/ref/create_server.sgml | 16 +- doc/src/sgml/ref/create_statistics.sgml | 8 +- doc/src/sgml/ref/create_subscription.sgml | 18 +- doc/src/sgml/ref/create_table.sgml | 100 ++-- doc/src/sgml/ref/create_table_as.sgml | 42 +- doc/src/sgml/ref/create_tablespace.sgml | 18 +- doc/src/sgml/ref/create_transform.sgml | 10 +- doc/src/sgml/ref/create_trigger.sgml | 18 +- doc/src/sgml/ref/create_tsconfig.sgml | 6 +- doc/src/sgml/ref/create_tsdictionary.sgml | 6 +- doc/src/sgml/ref/create_tsparser.sgml | 6 +- doc/src/sgml/ref/create_tstemplate.sgml | 6 +- doc/src/sgml/ref/create_type.sgml | 26 +- doc/src/sgml/ref/create_user.sgml | 4 +- doc/src/sgml/ref/create_user_mapping.sgml | 8 +- doc/src/sgml/ref/create_view.sgml | 26 +- doc/src/sgml/ref/createdb.sgml | 16 +- doc/src/sgml/ref/createuser.sgml | 16 +- doc/src/sgml/ref/deallocate.sgml | 6 +- doc/src/sgml/ref/declare.sgml | 28 +- doc/src/sgml/ref/delete.sgml | 10 +- doc/src/sgml/ref/discard.sgml | 2 +- doc/src/sgml/ref/do.sgml | 2 +- doc/src/sgml/ref/drop_access_method.sgml | 4 +- doc/src/sgml/ref/drop_aggregate.sgml | 8 +- doc/src/sgml/ref/drop_cast.sgml | 2 +- doc/src/sgml/ref/drop_collation.sgml | 6 +- doc/src/sgml/ref/drop_conversion.sgml | 4 +- doc/src/sgml/ref/drop_database.sgml | 4 +- doc/src/sgml/ref/drop_domain.sgml | 6 +- doc/src/sgml/ref/drop_event_trigger.sgml | 6 +- doc/src/sgml/ref/drop_extension.sgml | 6 +- .../sgml/ref/drop_foreign_data_wrapper.sgml | 6 +- doc/src/sgml/ref/drop_foreign_table.sgml | 6 +- doc/src/sgml/ref/drop_function.sgml | 6 +- doc/src/sgml/ref/drop_group.sgml | 4 +- doc/src/sgml/ref/drop_index.sgml | 4 +- doc/src/sgml/ref/drop_language.sgml | 8 +- doc/src/sgml/ref/drop_materialized_view.sgml | 8 +- doc/src/sgml/ref/drop_opclass.sgml | 8 +- doc/src/sgml/ref/drop_operator.sgml | 6 +- doc/src/sgml/ref/drop_opfamily.sgml | 12 +- doc/src/sgml/ref/drop_owned.sgml | 10 +- doc/src/sgml/ref/drop_policy.sgml | 4 +- doc/src/sgml/ref/drop_publication.sgml | 4 +- doc/src/sgml/ref/drop_role.sgml | 12 +- doc/src/sgml/ref/drop_rule.sgml | 6 +- doc/src/sgml/ref/drop_schema.sgml | 6 +- doc/src/sgml/ref/drop_sequence.sgml | 6 +- doc/src/sgml/ref/drop_server.sgml | 6 +- doc/src/sgml/ref/drop_statistics.sgml | 4 +- doc/src/sgml/ref/drop_subscription.sgml | 6 +- doc/src/sgml/ref/drop_table.sgml | 10 +- doc/src/sgml/ref/drop_tablespace.sgml | 6 +- doc/src/sgml/ref/drop_transform.sgml | 6 +- doc/src/sgml/ref/drop_trigger.sgml | 4 +- doc/src/sgml/ref/drop_tsconfig.sgml | 6 +- doc/src/sgml/ref/drop_tsdictionary.sgml | 6 +- doc/src/sgml/ref/drop_tsparser.sgml | 6 +- doc/src/sgml/ref/drop_tstemplate.sgml | 6 +- doc/src/sgml/ref/drop_type.sgml | 6 +- doc/src/sgml/ref/drop_user.sgml | 4 +- doc/src/sgml/ref/drop_user_mapping.sgml | 4 +- doc/src/sgml/ref/drop_view.sgml | 6 +- doc/src/sgml/ref/dropdb.sgml | 12 +- doc/src/sgml/ref/dropuser.sgml | 12 +- doc/src/sgml/ref/ecpg-ref.sgml | 4 +- doc/src/sgml/ref/end.sgml | 12 +- doc/src/sgml/ref/execute.sgml | 10 +- doc/src/sgml/ref/explain.sgml | 6 +- doc/src/sgml/ref/fetch.sgml | 12 +- doc/src/sgml/ref/grant.sgml | 32 +- doc/src/sgml/ref/import_foreign_schema.sgml | 4 +- doc/src/sgml/ref/initdb.sgml | 18 +- doc/src/sgml/ref/insert.sgml | 8 +- doc/src/sgml/ref/listen.sgml | 6 +- doc/src/sgml/ref/load.sgml | 6 +- doc/src/sgml/ref/lock.sgml | 16 +- doc/src/sgml/ref/move.sgml | 8 +- doc/src/sgml/ref/notify.sgml | 6 +- doc/src/sgml/ref/pg_basebackup.sgml | 28 +- doc/src/sgml/ref/pg_ctl-ref.sgml | 14 +- doc/src/sgml/ref/pg_dump.sgml | 46 +- doc/src/sgml/ref/pg_dumpall.sgml | 12 +- doc/src/sgml/ref/pg_isready.sgml | 4 +- doc/src/sgml/ref/pg_receivewal.sgml | 22 +- doc/src/sgml/ref/pg_recvlogical.sgml | 20 +- doc/src/sgml/ref/pg_resetwal.sgml | 2 +- doc/src/sgml/ref/pg_restore.sgml | 22 +- doc/src/sgml/ref/pg_rewind.sgml | 6 +- doc/src/sgml/ref/pg_waldump.sgml | 2 +- doc/src/sgml/ref/pgarchivecleanup.sgml | 6 +- doc/src/sgml/ref/pgbench.sgml | 6 +- doc/src/sgml/ref/pgtestfsync.sgml | 6 +- doc/src/sgml/ref/pgtesttiming.sgml | 2 +- doc/src/sgml/ref/pgupgrade.sgml | 20 +- doc/src/sgml/ref/postgres-ref.sgml | 52 +- doc/src/sgml/ref/postmaster.sgml | 2 +- doc/src/sgml/ref/prepare.sgml | 14 +- doc/src/sgml/ref/prepare_transaction.sgml | 14 +- doc/src/sgml/ref/psql-ref.sgml | 76 +-- doc/src/sgml/ref/reassign_owned.sgml | 10 +- .../sgml/ref/refresh_materialized_view.sgml | 8 +- doc/src/sgml/ref/reindex.sgml | 4 +- doc/src/sgml/ref/reindexdb.sgml | 12 +- doc/src/sgml/ref/release_savepoint.sgml | 12 +- doc/src/sgml/ref/reset.sgml | 12 +- doc/src/sgml/ref/revoke.sgml | 10 +- doc/src/sgml/ref/rollback.sgml | 8 +- doc/src/sgml/ref/rollback_prepared.sgml | 4 +- doc/src/sgml/ref/rollback_to.sgml | 12 +- doc/src/sgml/ref/savepoint.sgml | 14 +- doc/src/sgml/ref/security_label.sgml | 2 +- doc/src/sgml/ref/select.sgml | 68 +-- doc/src/sgml/ref/select_into.sgml | 16 +- doc/src/sgml/ref/set.sgml | 16 +- doc/src/sgml/ref/set_role.sgml | 8 +- doc/src/sgml/ref/set_session_auth.sgml | 6 +- doc/src/sgml/ref/set_transaction.sgml | 12 +- doc/src/sgml/ref/show.sgml | 12 +- doc/src/sgml/ref/start_transaction.sgml | 18 +- doc/src/sgml/ref/truncate.sgml | 4 +- doc/src/sgml/ref/unlisten.sgml | 6 +- doc/src/sgml/ref/update.sgml | 6 +- doc/src/sgml/ref/vacuum.sgml | 18 +- doc/src/sgml/ref/vacuumdb.sgml | 14 +- doc/src/sgml/ref/values.sgml | 16 +- doc/src/sgml/reference.sgml | 2 +- doc/src/sgml/regress.sgml | 12 +- doc/src/sgml/release-10.sgml | 80 +-- doc/src/sgml/release-7.4.sgml | 104 ++-- doc/src/sgml/release-8.0.sgml | 98 ++-- doc/src/sgml/release-8.1.sgml | 88 +-- doc/src/sgml/release-8.2.sgml | 78 +-- doc/src/sgml/release-8.3.sgml | 90 +-- doc/src/sgml/release-8.4.sgml | 86 +-- doc/src/sgml/release-9.0.sgml | 86 +-- doc/src/sgml/release-9.1.sgml | 98 ++-- doc/src/sgml/release-9.2.sgml | 114 ++-- doc/src/sgml/release-9.3.sgml | 112 ++-- doc/src/sgml/release-9.4.sgml | 240 ++++---- doc/src/sgml/release-9.5.sgml | 118 ++-- doc/src/sgml/release-9.6.sgml | 86 +-- doc/src/sgml/release-old.sgml | 22 +- doc/src/sgml/replication-origins.sgml | 2 +- doc/src/sgml/rowtypes.sgml | 10 +- doc/src/sgml/rules.sgml | 10 +- doc/src/sgml/runtime.sgml | 116 ++-- doc/src/sgml/seg.sgml | 8 +- doc/src/sgml/sepgsql.sgml | 18 +- doc/src/sgml/sourcerepo.sgml | 2 +- doc/src/sgml/sources.sgml | 10 +- doc/src/sgml/spgist.sgml | 18 +- doc/src/sgml/spi.sgml | 12 +- doc/src/sgml/standalone-install.xml | 12 +- doc/src/sgml/start.sgml | 10 +- doc/src/sgml/storage.sgml | 32 +- doc/src/sgml/syntax.sgml | 96 ++-- doc/src/sgml/tablefunc.sgml | 4 +- doc/src/sgml/tablesample-method.sgml | 2 +- doc/src/sgml/textsearch.sgml | 62 +-- doc/src/sgml/trigger.sgml | 20 +- doc/src/sgml/tsm-system-rows.sgml | 2 +- doc/src/sgml/tsm-system-time.sgml | 2 +- doc/src/sgml/typeconv.sgml | 24 +- doc/src/sgml/user-manag.sgml | 36 +- doc/src/sgml/uuid-ossp.sgml | 6 +- doc/src/sgml/vacuumlo.sgml | 4 +- doc/src/sgml/wal.sgml | 62 +-- doc/src/sgml/xaggr.sgml | 18 +- doc/src/sgml/xfunc.sgml | 66 +-- doc/src/sgml/xindex.sgml | 38 +- doc/src/sgml/xml2.sgml | 4 +- doc/src/sgml/xoper.sgml | 2 +- doc/src/sgml/xplang.sgml | 18 +- doc/src/sgml/xtypes.sgml | 6 +- src/Makefile.global.in | 2 - 346 files changed, 4257 insertions(+), 4585 deletions(-) diff --git a/config/docbook.m4 b/config/docbook.m4 index f9307f329e..34b829eade 100644 --- a/config/docbook.m4 +++ b/config/docbook.m4 @@ -1,18 +1,18 @@ # config/docbook.m4 -# PGAC_PROG_NSGMLS -# ---------------- -AC_DEFUN([PGAC_PROG_NSGMLS], -[PGAC_PATH_PROGS(NSGMLS, [onsgmls nsgmls])]) +# PGAC_PATH_XMLLINT +# ----------------- +AC_DEFUN([PGAC_PATH_XMLLINT], +[PGAC_PATH_PROGS(XMLLINT, xmllint)]) # PGAC_CHECK_DOCBOOK(VERSION) # --------------------------- AC_DEFUN([PGAC_CHECK_DOCBOOK], -[AC_REQUIRE([PGAC_PROG_NSGMLS]) -AC_CACHE_CHECK([for DocBook V$1], [pgac_cv_check_docbook], -[cat >conftest.sgml < +[AC_REQUIRE([PGAC_PATH_XMLLINT]) +AC_CACHE_CHECK([for DocBook XML V$1], [pgac_cv_check_docbook], +[cat >conftest.xml < test @@ -27,13 +27,13 @@ EOF pgac_cv_check_docbook=no -if test -n "$NSGMLS"; then - $NSGMLS -s conftest.sgml 1>&AS_MESSAGE_LOG_FD 2>&1 +if test -n "$XMLLINT"; then + $XMLLINT --noout --valid conftest.xml 1>&AS_MESSAGE_LOG_FD 2>&1 if test $? -eq 0; then pgac_cv_check_docbook=yes fi fi -rm -f conftest.sgml]) +rm -f conftest.xml]) have_docbook=$pgac_cv_check_docbook AC_SUBST([have_docbook]) diff --git a/configure b/configure index b31134832e..3203473f87 100755 --- a/configure +++ b/configure @@ -630,12 +630,10 @@ vpath_build PG_VERSION_NUM PROVE FOP -OSX XSLTPROC -XMLLINT DBTOEPUB have_docbook -NSGMLS +XMLLINT TCL_SHLIB_LD_LIBS TCL_SHARED_BUILD TCL_LIB_SPEC @@ -16132,19 +16130,19 @@ fi # # Check for DocBook and tools # -if test -z "$NSGMLS"; then - for ac_prog in onsgmls nsgmls +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_NSGMLS+:} false; then : +if ${ac_cv_path_XMLLINT+:} false; then : $as_echo_n "(cached) " >&6 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 @@ -16154,7 +16152,7 @@ do 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_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 break 2 fi @@ -16165,35 +16163,35 @@ IFS=$as_save_IFS ;; esac fi -NSGMLS=$ac_cv_path_NSGMLS -if test -n "$NSGMLS"; then - { $as_echo "$as_me:${as_lineno-$LINENO}: result: $NSGMLS" >&5 -$as_echo "$NSGMLS" >&6; } +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 "$NSGMLS" && break + test -n "$XMLLINT" && break done else - # Report the value of NSGMLS in configure's output in all cases. - { $as_echo "$as_me:${as_lineno-$LINENO}: checking for NSGMLS" >&5 -$as_echo_n "checking for NSGMLS... " >&6; } - { $as_echo "$as_me:${as_lineno-$LINENO}: result: $NSGMLS" >&5 -$as_echo "$NSGMLS" >&6; } + # 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 -{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for DocBook V4.2" >&5 -$as_echo_n "checking for DocBook V4.2... " >&6; } +{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for DocBook XML V4.2" >&5 +$as_echo_n "checking for DocBook XML V4.2... " >&6; } if ${pgac_cv_check_docbook+:} false; then : $as_echo_n "(cached) " >&6 else - cat >conftest.sgml < + cat >conftest.xml < test @@ -16208,13 +16206,13 @@ EOF pgac_cv_check_docbook=no -if test -n "$NSGMLS"; then - $NSGMLS -s conftest.sgml 1>&5 2>&1 +if test -n "$XMLLINT"; then + $XMLLINT --noout --valid conftest.xml 1>&5 2>&1 if test $? -eq 0; then pgac_cv_check_docbook=yes fi fi -rm -f conftest.sgml +rm -f conftest.xml fi { $as_echo "$as_me:${as_lineno-$LINENO}: result: $pgac_cv_check_docbook" >&5 $as_echo "$pgac_cv_check_docbook" >&6; } @@ -16276,60 +16274,6 @@ $as_echo_n "checking for DBTOEPUB... " >&6; } $as_echo "$DBTOEPUB" >&6; } 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 for ac_prog in xsltproc do @@ -16384,60 +16328,6 @@ $as_echo_n "checking for XSLTPROC... " >&6; } $as_echo "$XSLTPROC" >&6; } 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 for ac_prog in fop do diff --git a/configure.in b/configure.in index 3f26f038d6..d9c4a50b4b 100644 --- a/configure.in +++ b/configure.in @@ -2091,12 +2091,10 @@ fi # # Check for DocBook and tools # -PGAC_PROG_NSGMLS +PGAC_PATH_XMLLINT PGAC_CHECK_DOCBOOK(4.2) PGAC_PATH_PROGS(DBTOEPUB, dbtoepub) -PGAC_PATH_PROGS(XMLLINT, xmllint) PGAC_PATH_PROGS(XSLTPROC, xsltproc) -PGAC_PATH_PROGS(OSX, [osx sgml2xml sx]) PGAC_PATH_PROGS(FOP, fop) # diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index df77a142e4..f122b4187f 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -37,15 +37,7 @@ ifndef FOP FOP = $(missing) fop endif -SGMLINCLUDE = -D . -D $(srcdir) - -ifndef NSGMLS -NSGMLS = $(missing) nsgmls -endif - -ifndef OSX -OSX = $(missing) osx -endif +XMLINCLUDE = --path . ifndef XMLLINT XMLLINT = $(missing) xmllint @@ -63,19 +55,6 @@ GENERATED_SGML = version.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 . -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 @@ -83,9 +62,9 @@ endif man distprep-man: man-stamp -man-stamp: stylesheet-man.xsl postgres.xml - $(XMLLINT) --noout --valid postgres.xml - $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_MAN_FLAGS) $^ +man-stamp: stylesheet-man.xsl postgres.sgml $(ALLSGML) + $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) + $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_MAN_FLAGS) $(wordlist 1,2,$^) touch $@ @@ -136,27 +115,8 @@ INSTALL.html: %.html : stylesheet-text.xsl %.xml $(XMLLINT) --noout --valid $*.xml $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ >$@ -INSTALL.xml: standalone-profile.xsl standalone-install.xml postgres.xml - $(XSLTPROC) $(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{\n} if $$. == 1;' \ - <$@.tmp > $@ -rm $@.tmp -endef +INSTALL.xml: standalone-profile.xsl standalone-install.xml postgres.sgml $(ALLSGML) + $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --xinclude $(wordlist 1,2,$^) >$@ ## @@ -169,20 +129,20 @@ endif html: html-stamp -html-stamp: stylesheet.xsl postgres.xml - $(XMLLINT) --noout --valid postgres.xml - $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ +html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML) + $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) + $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $(wordlist 1,2,$^) cp $(srcdir)/stylesheet.css html/ touch $@ -htmlhelp: stylesheet-hh.xsl postgres.xml - $(XMLLINT) --noout --valid postgres.xml - $(XSLTPROC) $(XSLTPROCFLAGS) $^ +htmlhelp: stylesheet-hh.xsl postgres.sgml $(ALLSGML) + $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) + $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(wordlist 1,2,$^) # single-page HTML -postgres.html: stylesheet-html-nochunk.xsl postgres.xml - $(XMLLINT) --noout --valid postgres.xml - $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $^ +postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML) + $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) + $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $(wordlist 1,2,$^) # single-page text postgres.txt: postgres.html @@ -196,13 +156,13 @@ postgres.txt: postgres.html postgres.pdf: $(error Invalid target; use postgres-A4.pdf or postgres-US.pdf as targets) -%-A4.fo: stylesheet-fo.xsl %.xml - $(XMLLINT) --noout --valid $*.xml - $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type A4 -o $@ $^ +%-A4.fo: stylesheet-fo.xsl %.sgml $(ALLSGML) + $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) + $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type A4 -o $@ $(wordlist 1,2,$^) -%-US.fo: stylesheet-fo.xsl %.xml - $(XMLLINT) --noout --valid $*.xml - $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $^ +%-US.fo: stylesheet-fo.xsl %.sgml $(ALLSGML) + $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) + $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^) %.pdf: %.fo $(FOP) -fo $< -pdf $@ @@ -213,7 +173,7 @@ postgres.pdf: ## epub: postgres.epub -postgres.epub: postgres.xml +postgres.epub: postgres.sgml $(ALLSGML) $(XMLLINT) --noout --valid $< $(DBTOEPUB) $< @@ -226,7 +186,8 @@ DB2X_TEXIXML = db2x_texixml DB2X_XSLTPROC = db2x_xsltproc MAKEINFO = makeinfo -%.texixml: %.xml +%.texixml: %.sgml $(ALLSGML) + $(XMLLINT) --noout --valid $< $(DB2X_XSLTPROC) -s texi -g output-file=$(basename $@) $< -o $@ %.texi: %.texixml @@ -242,7 +203,7 @@ MAKEINFO = makeinfo # Quick syntax check without style processing 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 # keeping the dependencies satisfied. -.SECONDARY: postgres.xml $(GENERATED_SGML) +.SECONDARY: $(GENERATED_SGML) .SECONDARY: INSTALL.html INSTALL.xml .SECONDARY: postgres-A4.fo postgres-US.fo @@ -326,8 +287,6 @@ clean: rm -f *.fo *.pdf # generated SGML files rm -f $(GENERATED_SGML) -# SGML->XML conversion - rm -f postgres.xml *.tmp # HTML Help rm -f htmlhelp.hhp toc.hhc index.hhk # EPUB diff --git a/doc/src/sgml/adminpack.sgml b/doc/src/sgml/adminpack.sgml index b27a4a325d..1197eefbf3 100644 --- a/doc/src/sgml/adminpack.sgml +++ b/doc/src/sgml/adminpack.sgml @@ -16,9 +16,9 @@ - The functions shown in provide + The functions shown in provide write access to files on the machine hosting the server. (See also the - functions in , which + functions in , which provide read-only access.) Only files within the database cluster directory can be accessed, but either a relative or absolute path is allowable. @@ -107,18 +107,18 @@ pg_logdir_ls returns the start timestamps and path - names of all the log files in the - directory. The parameter must have its + names of all the log files in the + directory. The parameter must have its default setting (postgresql-%Y-%m-%d_%H%M%S.log) to use this function. The functions shown - in are deprecated + in are deprecated and should not be used in new applications; instead use those shown - in - and . These functions are + in + and . These functions are provided in adminpack only for compatibility with old versions of pgAdmin. diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml index bf87df4dcb..ae5f3fac75 100644 --- a/doc/src/sgml/advanced.sgml +++ b/doc/src/sgml/advanced.sgml @@ -18,12 +18,12 @@ This chapter will on occasion refer to examples found in 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 this chapter can also be found in advanced.sql in the tutorial directory. This file also contains some sample data to load, which is not - repeated here. (Refer to for + repeated here. (Refer to for how to use the file.) @@ -37,7 +37,7 @@ - Refer back to the queries in . + Refer back to the queries in . Suppose the combined listing of weather records and city location 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 @@ -82,7 +82,7 @@ SELECT * FROM myview; Recall the weather and cities tables from . 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 weather table that do not have a matching entry in the cities table. This is called @@ -129,7 +129,7 @@ DETAIL: Key (city)=(Berkeley) is not present in table "cities". The behavior of foreign keys can be finely tuned to your application. We will not go beyond this simple example in this - tutorial, but just refer you to + tutorial, but just refer you to for more information. Making correct use of foreign keys will definitely improve the quality of your database applications, so you are strongly encouraged to learn about them. @@ -447,7 +447,7 @@ FROM empsalary; There are options to define the window frame in other ways, but this tutorial does not cover them. See - for details. + for details. Here is an example using sum: @@ -554,10 +554,10 @@ SELECT sum(salary) OVER w, avg(salary) OVER w More details about window functions can be found in - , - , - , and the - reference page. + , + , + , and the + reference page. @@ -692,7 +692,7 @@ SELECT name, altitude Although inheritance is frequently useful, it has not been integrated with unique constraints or foreign keys, which limits its usefulness. - See for more detail. + See for more detail. diff --git a/doc/src/sgml/amcheck.sgml b/doc/src/sgml/amcheck.sgml index 0dd68f0ba1..852e260c09 100644 --- a/doc/src/sgml/amcheck.sgml +++ b/doc/src/sgml/amcheck.sgml @@ -31,7 +31,7 @@ index scans themselves, which may be user-defined operator class code. For example, B-Tree index verification relies on comparisons made with one or more B-Tree support function 1 routines. See for details of operator class support + linkend="xindex-support"/> for details of operator class support functions. @@ -192,7 +192,7 @@ ORDER BY c.relpages DESC LIMIT 10; index that is ordered using an affected collation, simply because indexed values might happen to have the same absolute ordering regardless of the behavioral inconsistency. See - and for + and for further details about how PostgreSQL uses operating system locales and collations. @@ -210,7 +210,7 @@ ORDER BY c.relpages DESC LIMIT 10; logical inconsistency to be introduced. One obvious testing strategy is to call amcheck functions continuously when running the standard regression tests. See for details on running the tests. + linkend="regress-run"/> for details on running the tests. @@ -263,7 +263,7 @@ ORDER BY c.relpages DESC LIMIT 10; There is no general method of repairing problems that amcheck detects. An explanation for the root cause of an invariant violation should be sought. may play a useful role in diagnosing + linkend="pageinspect"/> may play a useful role in diagnosing corruption that amcheck detects. A REINDEX may not be effective in repairing corruption. diff --git a/doc/src/sgml/arch-dev.sgml b/doc/src/sgml/arch-dev.sgml index d49901c690..53f8049df3 100644 --- a/doc/src/sgml/arch-dev.sgml +++ b/doc/src/sgml/arch-dev.sgml @@ -7,7 +7,7 @@ Author This chapter originated as part of - , Stefan Simkovics' + , Stefan Simkovics' 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. @@ -136,7 +136,7 @@ The client process can be any program that understands the PostgreSQL protocol described in - . Many clients are based on the + . Many clients are based on the C-language library libpq, but several independent implementations of the protocol exist, such as the Java JDBC driver. @@ -317,7 +317,7 @@ The query rewriter is discussed in some detail in - , so there is no need to cover it here. + , so there is no need to cover it here. 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 representation or level of semantic detail in the trees. Rewriting @@ -347,8 +347,8 @@ involving large numbers of join operations. In order to determine a reasonable (not necessarily optimal) query plan in a reasonable amount of time, PostgreSQL uses a Genetic - Query Optimizer (see ) when the number of joins - exceeds a threshold (see ). + Query Optimizer (see ) when the number of joins + exceeds a threshold (see ). @@ -438,7 +438,7 @@ - If the query uses fewer than + If the query uses fewer than relations, a near-exhaustive search is conducted to find the best join sequence. The planner preferentially considers joins between any two relations for which there exist a corresponding join clause in the @@ -454,7 +454,7 @@ When geqo_threshold is exceeded, the join sequences considered are determined by heuristics, as described - in . Otherwise the process is the same. + in . Otherwise the process is the same. diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml index 9187f6e02e..f4d4a610ef 100644 --- a/doc/src/sgml/array.sgml +++ b/doc/src/sgml/array.sgml @@ -128,7 +128,7 @@ CREATE TABLE tictactoe ( (These kinds of array constants are actually only a special case of the generic type constants discussed in . The constant is initially + linkend="sql-syntax-constants-generic"/>. The constant is initially treated as a string and passed to the array input conversion routine. An explicit type specification might be necessary.) @@ -192,7 +192,7 @@ INSERT INTO sal_emp expressions; for instance, string literals are single quoted, instead of double quoted as they would be in an array literal. The ARRAY constructor syntax is discussed in more detail in - . + . @@ -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 helpful if the size of the array is unknown. An alternative method is - described in . The above + described in . The above query could be replaced by: @@ -644,7 +644,7 @@ SELECT * FROM WHERE pay_by_quarter[s] = 10000; - This function is described in . + This function is described in . @@ -657,8 +657,8 @@ SELECT * FROM sal_emp WHERE pay_by_quarter && ARRAY[10000]; This and other array operators are further described in - . It can be accelerated by an appropriate - index, as described in . + . It can be accelerated by an appropriate + index, as described in . @@ -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 NULL to be entered. Also, for backward compatibility with pre-8.2 versions of PostgreSQL, the configuration parameter can be turned + linkend="guc-array-nulls"/> configuration parameter can be turned off to suppress recognition of NULL as a NULL. @@ -797,7 +797,7 @@ INSERT ... VALUES (E'{"\\\\","\\""}'); with a data type whose input routine also treated backslashes specially, bytea for example, we might need as many as eight backslashes in the command to get one backslash into the stored array element.) - Dollar quoting (see ) can be + Dollar quoting (see ) can be used to avoid the need to double backslashes. @@ -805,7 +805,7 @@ INSERT ... VALUES (E'{"\\\\","\\""}'); The ARRAY constructor syntax (see - ) is often easier to work + ) is often easier to work with than the array-literal syntax when writing array values in SQL commands. In ARRAY, individual element values are written the same way they would be written when not members of an array. diff --git a/doc/src/sgml/auth-delay.sgml b/doc/src/sgml/auth-delay.sgml index 9221d2dfb6..bd3ef7128d 100644 --- a/doc/src/sgml/auth-delay.sgml +++ b/doc/src/sgml/auth-delay.sgml @@ -18,7 +18,7 @@ In order to function, this module must be loaded via - in postgresql.conf. + in postgresql.conf. diff --git a/doc/src/sgml/auto-explain.sgml b/doc/src/sgml/auto-explain.sgml index 240098c82f..08b67f2600 100644 --- a/doc/src/sgml/auto-explain.sgml +++ b/doc/src/sgml/auto-explain.sgml @@ -10,7 +10,7 @@ The auto_explain module provides a means for logging execution plans of slow statements automatically, without - having to run + having to run by hand. This is especially helpful for tracking down un-optimized queries in large applications. @@ -25,8 +25,8 @@ LOAD 'auto_explain'; (You must be superuser to do that.) More typical usage is to preload it into some or all sessions by including auto_explain in - or - in + or + in postgresql.conf. Then you can track unexpectedly slow queries no matter when they happen. Of course there is a price in overhead for that. diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml index 39bb25c8e2..9d8e69056f 100644 --- a/doc/src/sgml/backup.sgml +++ b/doc/src/sgml/backup.sgml @@ -32,7 +32,7 @@ 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. PostgreSQL provides the utility program - for this purpose. The basic usage of this + for this purpose. The basic usage of this command is: pg_dump dbname > outfile @@ -79,7 +79,7 @@ pg_dump dbname > PGUSER. Remember that pg_dump connections are subject to the normal client authentication mechanisms (which are described in ). + linkend="client-authentication"/>). @@ -120,9 +120,9 @@ psql dbname < dbname). psql supports options similar to pg_dump for specifying the database server to connect to and the user name to use. See - the reference page for more information. + the reference page for more information. Non-text file dumps are restored using the utility. + linkend="app-pgrestore"/> utility. @@ -178,13 +178,13 @@ pg_dump -h host1 dbname | After restoring a backup, it is wise to run on each + linkend="sql-analyze"/> on each database so the query optimizer has useful statistics; - see - and for more information. + see + and for more information. For more advice on how to load large amounts of data into PostgreSQL efficiently, refer to . + linkend="populate"/>. @@ -196,7 +196,7 @@ pg_dump -h host1 dbname | and it does not dump information about roles or tablespaces (because those are cluster-wide rather than per-database). To support convenient dumping of the entire contents of a database - cluster, the program is provided. + cluster, the program is provided. pg_dumpall backs up each database in a given cluster, and also preserves cluster-wide data such as role and tablespace definitions. The basic usage of this command is: @@ -308,8 +308,8 @@ pg_dump -Fc dbname > dbname filename - See the and reference pages for details. + See the and reference pages for details. @@ -345,7 +345,7 @@ pg_dump -j num -F d -f An alternative backup strategy is to directly copy the files that PostgreSQL uses to store the data in the database; - explains where these files + explains where these files are located. You can use whatever method you prefer 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, but also because of internal buffering within the server). Information about stopping the server can be found in - . Needless to say, you + . Needless to say, you also need to shut down the server before restoring the data. @@ -428,10 +428,10 @@ tar -cf backup.tar /usr/local/pgsql/data If simultaneous snapshots are not possible, one option is to shut down the database server long enough to establish all the frozen snapshots. Another option is to perform a continuous archiving 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 archiving just during the backup process; restore is done using - continuous archive recovery (). + continuous archive recovery (). @@ -591,11 +591,11 @@ tar -cf backup.tar /usr/local/pgsql/data - To enable WAL archiving, set the + To enable WAL archiving, set the configuration parameter to replica or higher, - to on, + to on, and specify the shell command to use in the configuration parameter. In practice + linkend="guc-archive-command"/> configuration parameter. In practice these settings will always be placed in the postgresql.conf file. In archive_command, @@ -705,7 +705,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0 than through SQL operations. You might wish to keep the configuration files in a location that will be backed up by your regular file system backup procedures. See - for how to relocate the + for how to relocate the configuration files. @@ -715,7 +715,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0 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 a limit on how old unarchived data can be, you can set - to force the server to switch + to force the server to switch 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 length as completely full files. It is therefore unwise to set a very @@ -729,13 +729,13 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0 pg_switch_wal if you want to ensure that a just-finished transaction is archived as soon as possible. Other utility functions related to WAL management are listed in . + linkend="functions-admin-backup-table"/>. When wal_level is minimal some SQL commands are optimized to avoid WAL logging, as described in . 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 contain enough information for archive recovery. (Crash recovery is unaffected.) For this reason, wal_level can only be changed at @@ -753,11 +753,11 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0 The easiest way to perform a base backup is to use the - tool. It can create + tool. It can create a base backup either as regular files or as a tar archive. If more - flexibility than can provide is + flexibility than can provide is required, you can also make a base backup using the low level API - (see ). + (see ). @@ -791,7 +791,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0 The backup history file is just a small text file. It contains the - label string you gave to , as well as + label string you gave to , as well as the starting and ending times and WAL segments of the backup. 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 @@ -814,7 +814,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0 The procedure for making a base backup using the low level APIs contains a few more steps than - the method, but is relatively + the method, but is relatively simple. It is very important that these steps are executed in sequence, and that the success of a step is verified before proceeding to the next step. @@ -830,7 +830,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 && cp pg_wal/0 A non-exclusive low level backup is one that allows other concurrent backups to be running (both those started using the same backup API and those started using - ). + ). @@ -859,7 +859,7 @@ SELECT pg_start_backup('label', false, false); required for the checkpoint will be spread out over a significant period of time, by default half your inter-checkpoint interval (see the configuration parameter - ). This is + ). This is usually what you want, because it minimizes the impact on query processing. If you want to start the backup as soon as possible, change the second parameter to true, which will @@ -879,7 +879,7 @@ SELECT pg_start_backup('label', false, false); pg_dumpall). It is neither necessary nor desirable to stop normal operation of the database while you do this. See - for things to + for things to consider during this backup. @@ -989,7 +989,7 @@ SELECT pg_start_backup('label'); required for the checkpoint will be spread out over a significant period of time, by default half your inter-checkpoint interval (see the configuration parameter - ). This is + ). This is usually what you want, because it minimizes the impact on query processing. If you want to start the backup as soon as possible, use: @@ -1007,7 +1007,7 @@ SELECT pg_start_backup('label', true); pg_dumpall). It is neither necessary nor desirable to stop normal operation of the database while you do this. See - for things to + for things to consider during this backup. @@ -1119,7 +1119,7 @@ SELECT pg_stop_backup(); pg_snapshots/, pg_stat_tmp/, and pg_subtrans/ (but not the directories themselves) can be omitted from the backup as they will be initialized on postmaster startup. - If is set and is under the data + If is set and is under the data directory then the contents of that directory can also be omitted. @@ -1221,7 +1221,7 @@ SELECT pg_stop_backup(); Create a recovery command file recovery.conf in the cluster - data directory (see ). You might + data directory (see ). You might also want to temporarily modify pg_hba.conf to prevent ordinary users from connecting until you are sure the recovery was successful. @@ -1310,7 +1310,7 @@ restore_command = 'cp /mnt/server/archivedir/%f %p' at the start of recovery for a file named something like 00000001.history. This is also normal and does not indicate a problem in simple recovery situations; see - for discussion. + for discussion. @@ -1440,7 +1440,7 @@ restore_command = 'cp /mnt/server/archivedir/%f %p' As with base backups, the easiest way to produce a standalone - hot backup is to use the + hot backup is to use the tool. If you include the -X parameter when calling it, all the write-ahead log required to use the backup will be included in the backup automatically, and no special action is @@ -1548,7 +1548,7 @@ archive_command = 'local_backup_script.sh "%p" "%f"' When using an archive_command script, it's desirable - to enable . + to enable . Any messages written to stderr from the script will then appear in the database server log, allowing complex configurations to be diagnosed easily if they fail. @@ -1567,7 +1567,7 @@ archive_command = 'local_backup_script.sh "%p" "%f"' - If a + If a command is executed while a base backup is being taken, and then the template database that the CREATE DATABASE copied is modified while the base backup is still in progress, it is @@ -1580,7 +1580,7 @@ archive_command = 'local_backup_script.sh "%p" "%f"' - + commands are WAL-logged with the literal absolute path, and will therefore be replayed as tablespace creations with the same 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 be small enough to ignore, in which case you can significantly reduce the total volume of archived logs by turning off page - snapshots using the - parameter. (Read the notes and warnings in + snapshots using the + parameter. (Read the notes and warnings in before you do so.) Turning off page snapshots does not prevent use of the logs for PITR operations. An area for future development is to compress archived WAL data by removing diff --git a/doc/src/sgml/bgworker.sgml b/doc/src/sgml/bgworker.sgml index 0b092f6e49..4bc2b696b3 100644 --- a/doc/src/sgml/bgworker.sgml +++ b/doc/src/sgml/bgworker.sgml @@ -286,6 +286,6 @@ typedef struct BackgroundWorker The maximum number of registered background workers is limited by - . + . diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml index b7483df4c0..23c0e05ed6 100644 --- a/doc/src/sgml/brin.sgml +++ b/doc/src/sgml/brin.sgml @@ -95,7 +95,7 @@ The core PostgreSQL distribution includes the BRIN operator classes shown in - . + . @@ -590,7 +590,7 @@ typedef struct BrinOpcInfo To write an operator class for a data type that implements a totally ordered set, it is possible to use the minmax support procedures alongside the corresponding operators, as shown in - . + . All operator class members (procedures and operators) are mandatory. @@ -648,7 +648,7 @@ typedef struct BrinOpcInfo 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 procedures alongside the corresponding operators, as shown - in . It requires + in . It requires only a single additional function, which can be written in any language. More functions can be defined for additional functionality. All operators 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 of operators. Inclusion operator class operator strategies are dependent on another operator strategy as shown in - , or the same + , or the same operator strategy as themselves. They require the dependency operator to be defined with the STORAGE data type as the left-hand-side argument and the other supported data type to be the diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index ef60a58631..da881a7737 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -27,7 +27,7 @@ Overview - lists the system catalogs. + lists the system catalogs. More detailed documentation of each catalog follows below. @@ -567,8 +567,8 @@ New aggregate functions are registered with the - command. See for more information about + linkend="sql-createaggregate"/> + command. See for more information about writing aggregate functions and the meaning of the transition functions, etc. @@ -588,7 +588,7 @@ relation access methods. There is one row for each access method supported by the system. Currently, only indexes have access methods. The requirements for index - access methods are discussed in detail in . + access methods are discussed in detail in . @@ -649,7 +649,7 @@ methods. That data is now only directly visible at the C code level. However, pg_index_column_has_property() and related functions have been added to allow SQL queries to inspect index access - method properties; see . + method properties; see . @@ -1034,7 +1034,7 @@ attstattarget controls the level of detail of statistics accumulated for this column by - . + . A zero value indicates that no statistics should be collected. A negative value says to use the system default statistics target. The exact meaning of positive values is data type-dependent. @@ -1270,7 +1270,7 @@ - contains detailed information about user and + contains detailed information about user and privilege management. @@ -1356,7 +1356,7 @@ bool Role bypasses every row level security policy, see - for more information. + for more information. @@ -1964,8 +1964,8 @@ SCRAM-SHA-256$<iteration count>:&l Access privileges; see - and - + and + for details @@ -2015,7 +2015,7 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_collation describes the available collations, which are essentially mappings from an SQL name to operating system locale categories. - See for more information. + See for more information.
@@ -2424,7 +2424,7 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_conversion describes - encoding conversion procedures. See + encoding conversion procedures. See for more information. @@ -2516,8 +2516,8 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_database stores information about the available databases. Databases are created with the command. - Consult for details about the meaning + linkend="sql-createdatabase"/> command. + Consult for details about the meaning of some of the parameters. @@ -2675,8 +2675,8 @@ SCRAM-SHA-256$<iteration count>:&l Access privileges; see - and - + and + for details @@ -3053,7 +3053,7 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_description stores optional descriptions (comments) for each database object. Descriptions can be manipulated - with the command and viewed with + with the command and viewed with psql's \d commands. Descriptions of many built-in system objects are provided in the initial contents of pg_description. @@ -3208,7 +3208,7 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_event_trigger stores event triggers. - See for more information. + See for more information.
@@ -3258,7 +3258,7 @@ SCRAM-SHA-256$<iteration count>:&l char - Controls in which modes + Controls in which modes the event trigger fires. O = trigger fires in origin and local modes, D = trigger is disabled, @@ -3291,7 +3291,7 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_extension stores information - about the installed extensions. See + about the installed extensions. See for details about extensions. @@ -3463,8 +3463,8 @@ SCRAM-SHA-256$<iteration count>:&l Access privileges; see - and - + and + for details @@ -3559,8 +3559,8 @@ SCRAM-SHA-256$<iteration count>:&l Access privileges; see - and - + and + for details @@ -4011,8 +4011,8 @@ SCRAM-SHA-256$<iteration count>:&l The initial access privileges; see - and - + and + for details @@ -4034,8 +4034,8 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_language registers languages in which you can write functions or stored procedures. - See - and for more information about language handlers. + See + and for more information about language handlers.
@@ -4117,7 +4117,7 @@ SCRAM-SHA-256$<iteration count>:&l This references a function that is responsible for executing inline anonymous code blocks - ( blocks). + ( blocks). Zero if inline blocks are not supported. @@ -4139,8 +4139,8 @@ SCRAM-SHA-256$<iteration count>:&l Access privileges; see - and - + and + for details @@ -4279,8 +4279,8 @@ SCRAM-SHA-256$<iteration count>:&l Access privileges; see - and - + and + for details @@ -4346,8 +4346,8 @@ SCRAM-SHA-256$<iteration count>:&l Access privileges; see - and - + and + for details @@ -4377,7 +4377,7 @@ SCRAM-SHA-256$<iteration count>:&l - Operator classes are described at length in . + Operator classes are described at length in .
@@ -4481,8 +4481,8 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_operator stores information about operators. - See - and for more information. + See + and for more information.
@@ -4639,7 +4639,7 @@ SCRAM-SHA-256$<iteration count>:&l - Operator families are described at length in . + Operator families are described at length in .
@@ -5040,8 +5040,8 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_proc stores information about functions (or procedures). - See - and for more information. + See + and for more information. @@ -5106,7 +5106,7 @@ SCRAM-SHA-256$<iteration count>:&l float4 Estimated execution cost (in units of - ); if proretset, + ); if proretset, this is cost per row returned @@ -5130,7 +5130,7 @@ SCRAM-SHA-256$<iteration count>:&l regproc pg_proc.oid Calls to this function can be simplified by this other function - (see ) + (see ) @@ -5359,8 +5359,8 @@ SCRAM-SHA-256$<iteration count>:&l Access privileges; see - and - + and + for details @@ -5390,7 +5390,7 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_publication contains all publications created in the database. For more on publications see - . + .
@@ -5475,7 +5475,7 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_publication_rel contains the mapping between relations and publications in the database. This is a - many-to-many mapping. See also + many-to-many mapping. See also for a more user-friendly view of this information. @@ -5605,7 +5605,7 @@ SCRAM-SHA-256$<iteration count>:&l The pg_replication_origin catalog contains all replication origins created. For more on replication origins - see . + see .
@@ -5705,7 +5705,7 @@ SCRAM-SHA-256$<iteration count>:&l char - Controls in which modes + Controls in which modes the rule fires. O = rule fires in origin and local modes, D = rule is disabled, @@ -5765,8 +5765,8 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_seclabel stores security labels on database objects. Security labels can be manipulated - with the command. For an easier - way to view security labels, see . + with the command. For an easier + way to view security labels, see . @@ -6093,7 +6093,7 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_shdescription stores optional descriptions (comments) for shared database objects. Descriptions can be - manipulated with the command and viewed with + manipulated with the command and viewed with psql's \d commands. @@ -6160,8 +6160,8 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_shseclabel stores security labels on shared database objects. Security labels can be manipulated - with the command. For an easier - way to view security labels, see . + with the command. For an easier + way to view security labels, see . @@ -6228,7 +6228,7 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_statistic stores statistical data about the contents of the database. Entries are - created by + created by and subsequently used by the query planner. Note that all the statistical data is inherently approximate, even assuming that it is up-to-date. @@ -6408,7 +6408,7 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_statistic_ext holds extended planner statistics. Each row in this catalog corresponds to a statistics object - created with . + created with .
@@ -6521,7 +6521,7 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_subscription contains all existing logical replication subscriptions. For more information about logical - replication see . + replication see . @@ -6616,7 +6616,7 @@ SCRAM-SHA-256$<iteration count>:&l Array of subscribed publication names. These reference the publications on the publisher server. For more on publications - see . + see . @@ -6758,8 +6758,8 @@ SCRAM-SHA-256$<iteration count>:&l Access privileges; see - and - + and + for details @@ -6788,7 +6788,7 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_transform stores information about transforms, which are a mechanism to adapt data types to procedural - languages. See for more information. + languages. See for more information.
@@ -6856,7 +6856,7 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_trigger stores triggers on tables and views. - See + See for more information. @@ -6914,7 +6914,7 @@ SCRAM-SHA-256$<iteration count>:&l char - Controls in which modes + Controls in which modes the trigger fires. O = trigger fires in origin and local modes, D = trigger is disabled, @@ -7066,7 +7066,7 @@ SCRAM-SHA-256$<iteration count>:&l PostgreSQL's text search features are - described at length in . + described at length in .
@@ -7141,7 +7141,7 @@ SCRAM-SHA-256$<iteration count>:&l PostgreSQL's text search features are - described at length in . + described at length in .
@@ -7212,7 +7212,7 @@ SCRAM-SHA-256$<iteration count>:&l PostgreSQL's text search features are - described at length in . + described at length in .
@@ -7295,7 +7295,7 @@ SCRAM-SHA-256$<iteration count>:&l PostgreSQL's text search features are - described at length in . + described at length in .
@@ -7392,7 +7392,7 @@ SCRAM-SHA-256$<iteration count>:&l PostgreSQL's text search features are - described at length in . + described at length in .
@@ -7461,9 +7461,9 @@ SCRAM-SHA-256$<iteration count>:&l The catalog pg_type stores information about data types. Base types and enum types (scalar types) are created with - , and + , and domains with - . + . 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 composite types with CREATE TYPE AS. @@ -7567,7 +7567,7 @@ SCRAM-SHA-256$<iteration count>:&l typcategory is an arbitrary classification of data types that is used by the parser to determine which implicit casts should be preferred. - See . + See . @@ -7871,8 +7871,8 @@ SCRAM-SHA-256$<iteration count>:&l Access privileges; see - and - + and + for details @@ -7881,7 +7881,7 @@ SCRAM-SHA-256$<iteration count>:&l
- lists the system-defined values + lists the system-defined values of typcategory. Any future additions to this list will also be upper-case ASCII letters. All other ASCII characters are reserved for user-defined categories. @@ -8043,7 +8043,7 @@ SCRAM-SHA-256$<iteration count>:&l - The information schema () provides + The information schema () provides an alternative set of views which overlap the functionality of the system views. Since the information schema is SQL-standard whereas the views described here are PostgreSQL-specific, @@ -8052,11 +8052,11 @@ SCRAM-SHA-256$<iteration count>:&l - lists the system views described here. + lists the system views described here. More detailed documentation of each view follows below. There are some additional views that provide access to the results of the statistics collector; they are described in . + linkend="monitoring-stats-views-table"/>. @@ -8389,7 +8389,7 @@ SCRAM-SHA-256$<iteration count>:&l be used by software packages that want to interface to PostgreSQL to facilitate finding the required header files and libraries. It provides the same basic information as the - PostgreSQL client + PostgreSQL client application. @@ -8440,7 +8440,7 @@ SCRAM-SHA-256$<iteration count>:&l - via the + via the statement in SQL @@ -8448,14 +8448,14 @@ SCRAM-SHA-256$<iteration count>:&l via the Bind message in the frontend/backend protocol, as - described in + described in via the Server Programming Interface (SPI), as described in - + @@ -8648,7 +8648,7 @@ SCRAM-SHA-256$<iteration count>:&l - See for more information about the various + See for more information about the various ways to change run-time parameters. @@ -8813,7 +8813,7 @@ SCRAM-SHA-256$<iteration count>:&l - See for more information about + See for more information about client authentication configuration. @@ -8890,7 +8890,7 @@ SCRAM-SHA-256$<iteration count>:&l The view pg_locks provides access to information about the locks held by active processes within the - database server. See for more discussion + database server. See for more discussion of locking. @@ -9053,7 +9053,7 @@ SCRAM-SHA-256$<iteration count>:&l text Name of the lock mode held or desired by this process (see and ) + linkend="locking-tables"/> and ) granted @@ -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 on behalf of which other client sessions. It is better to use the pg_blocking_pids() function - (see ) to identify which + (see ) to identify which process(es) a waiting process is blocked behind. @@ -9369,7 +9369,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx The pg_prepared_statements view displays all the prepared statements that are available in the current - session. See for more information about prepared + session. See for more information about prepared statements. @@ -9377,7 +9377,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx pg_prepared_statements contains one row for each prepared statement. Rows are added to the view when a new prepared statement is created and removed when a prepared statement - is released (for example, via the command). + is released (for example, via the command). @@ -9457,7 +9457,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx The view pg_prepared_xacts displays information about transactions that are currently prepared for two-phase - commit (see for details). + commit (see for details). @@ -9601,7 +9601,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx The pg_replication_origin_status view contains information about how far replay for a certain origin has progressed. For more on replication origins - see . + see .
@@ -9670,7 +9670,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx For more on replication slots, - see and . + see and .
@@ -9917,7 +9917,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx Role bypasses every row level security policy, see - for more information. + for more information. @@ -10203,8 +10203,8 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx The view pg_settings provides access to run-time parameters of the server. It is essentially an alternative - interface to the - and commands. + interface to the + and commands. It also provides access to some facts about each parameter that are not directly available from SHOW, such as minimum and maximum values. @@ -10441,7 +10441,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx - See for more information about the various + See for more information about the various ways to change these parameters. @@ -10449,7 +10449,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx The pg_settings view cannot be inserted into or deleted from, but it can be updated. An UPDATE applied to a row of pg_settings is equivalent to executing - the command on that named + the command on that named parameter. The change only affects the value used by the current session. If an UPDATE is issued within a transaction that is later aborted, the effects of the UPDATE command @@ -10543,7 +10543,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx User bypasses every row level security policy, see - for more information. + for more information. @@ -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 column-by-column basis using the ALTER TABLE SET STATISTICS command, or globally by setting the - run-time parameter. + run-time parameter. @@ -10858,7 +10858,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx The view pg_timezone_abbrevs provides a list of time zone abbreviations that are currently recognized by the datetime input routines. The contents of this view change when the - run-time parameter is modified. + run-time parameter is modified.
@@ -10895,7 +10895,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx While most timezone abbreviations represent fixed offsets from UTC, there are some that have historically varied in value - (see for more information). + (see for more information). In such cases this view presents their current meaning. @@ -11025,7 +11025,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx bool User bypasses every row level security policy, see - for more information. + for more information. diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml index ce395e115a..dc3fd34a62 100644 --- a/doc/src/sgml/charset.sgml +++ b/doc/src/sgml/charset.sgml @@ -15,8 +15,8 @@ Using the locale features of the operating system to provide locale-specific collation order, number formatting, translated messages, and other aspects. - This is covered in and - . + This is covered in and + . @@ -25,7 +25,7 @@ Providing a number of different character sets to support storing text in all kinds of languages, and providing character set translation between client and server. - This is covered in . + This is covered in . @@ -146,7 +146,7 @@ initdb --locale=sv_SE the sort order of indexes, so they must be kept fixed, or indexes on text columns would become corrupt. (But you can alleviate this restriction using collations, as discussed - in .) + in .) The default values for these categories are determined when initdb is run, and 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 by setting the server configuration parameters that have the same name as the locale categories (see for details). The values + linkend="runtime-config-client-format"/> for details). The values that are chosen by initdb are actually only written into the configuration file postgresql.conf to serve as defaults when the server is started. If you remove these @@ -267,10 +267,10 @@ initdb --locale=sv_SE with LIKE clauses under a non-C locale, several custom operator classes exist. These allow the creation of an index that performs a strict character-by-character comparison, ignoring - locale comparison rules. Refer to + locale comparison rules. Refer to for more information. Another approach is to create indexes using the C collation, as discussed in - . + . @@ -316,7 +316,7 @@ initdb --locale=sv_SE PostgreSQL speak their preferred language well. If messages in your language are currently not available or not fully translated, your assistance would be appreciated. If you want to - help, refer to or write to the developers' + help, refer to or write to the developers' mailing list. @@ -524,7 +524,7 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR"; these under one concept than to create another infrastructure for setting LC_CTYPE per expression.) Also, a libc collation - is tied to a character set encoding (see ). + is tied to a character set encoding (see ). The same collation name may exist for different encodings. @@ -605,7 +605,7 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR"; for LC_COLLATE and LC_CTYPE, or if new locales are installed in the operating system after the database system was initialized, then a new collation may be created using - the command. + the command. New operating system locales can also be imported en masse using the pg_import_system_collations() function. @@ -702,7 +702,7 @@ SELECT a COLLATE "C" < b COLLATE "POSIX" FROM test1; If the standard and predefined collations are not sufficient, users can create their own collation objects using the SQL - command . + command . @@ -730,7 +730,7 @@ CREATE COLLATION german (provider = libc, locale = 'de_DE'); defined in the operating system when the database instance is initialized, it is not often necessary to manually create new ones. Reasons might be if a different naming system is desired (in which case - see also ) or if the operating system has + see also ) or if the operating system has been upgraded to provide new locale definitions (in which case see also pg_import_system_collations()). @@ -871,7 +871,7 @@ CREATE COLLATION german (provider = libc, locale = 'de_DE'); Copying Collations - The command can also be used to + The command can also be used to create a new collation from an existing collation, which can be useful to be able to use operating-system-independent collation names in applications, create compatibility names, or use an ICU-provided collation @@ -924,7 +924,7 @@ CREATE COLLATION french FROM "fr-x-icu"; Supported Character Sets - shows the character sets available + shows the character sets available for use in PostgreSQL. @@ -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 settings cannot be changed from those of the source database, because that might result in corrupt data. For more information see - . + . @@ -1449,7 +1449,7 @@ $ psql -l character set combinations. The conversion information is stored in the pg_conversion system catalog. PostgreSQL comes with some predefined conversions, as shown in . You can create a new + linkend="multibyte-translation-table"/>. You can create a new conversion using the SQL command CREATE CONVERSION. @@ -1763,7 +1763,7 @@ $ psql -l - libpq () has functions to control the client encoding. + libpq () has functions to control the client encoding. @@ -1812,7 +1812,7 @@ RESET client_encoding; Using the configuration variable . If the + linkend="guc-client-encoding"/>. If the client_encoding variable is set, that client encoding is automatically selected when a connection to the server is made. (This can subsequently be overridden using any diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index 99921ba079..c8a1bc79aa 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -13,13 +13,13 @@ 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 user name determines access privileges to database objects — see - for more information. Therefore, it is + for more information. Therefore, it is essential to restrict which database users can connect. - As explained in , + As explained in , PostgreSQL actually does privilege management in terms of roles. In this chapter, we consistently use database user to mean role with the @@ -70,7 +70,7 @@ pg_hba.conf file is installed when the data directory is initialized by initdb. It is possible to place the authentication configuration file elsewhere, - however; see the configuration parameter. + however; see the configuration parameter. @@ -136,7 +136,7 @@ hostnossl database user Remote TCP/IP connections will not be possible unless the server is started with an appropriate value for the - configuration parameter, + configuration parameter, since the default behavior is to listen for TCP/IP connections only on the local loopback address localhost. @@ -157,8 +157,8 @@ hostnossl database user To make use of this option the server must be built with SSL support. Furthermore, SSL must be enabled - by setting the configuration parameter (see - for more information). + by setting the configuration parameter (see + for more information). Otherwise, the hostssl record is ignored except for logging a warning that it cannot match any connections. @@ -381,7 +381,7 @@ hostnossl database user Specifies the authentication method to use when a connection matches this record. The possible choices are summarized here; details - are in . + are in . @@ -393,7 +393,7 @@ hostnossl database user PostgreSQL database server to login as any PostgreSQL user they wish, without the need for a password or any other authentication. See for details. + linkend="auth-trust"/> for details. @@ -416,7 +416,7 @@ hostnossl database user Perform SCRAM-SHA-256 authentication to verify the user's - password. See for details. + password. See for details. @@ -426,7 +426,7 @@ hostnossl database user Perform SCRAM-SHA-256 or MD5 authentication to verify the - user's password. See + user's password. See for details. @@ -440,7 +440,7 @@ hostnossl database user authentication. Since the password is sent in clear text over the network, this should not be used on untrusted networks. - See for details. + See for details. @@ -451,7 +451,7 @@ hostnossl database user Use GSSAPI to authenticate the user. This is only available for TCP/IP connections. See for details. + linkend="gssapi-auth"/> for details. @@ -462,7 +462,7 @@ hostnossl database user Use SSPI to authenticate the user. This is only available on Windows. See for details. + linkend="sspi-auth"/> for details. @@ -477,7 +477,7 @@ hostnossl database user Ident authentication can only be used on TCP/IP connections. When specified for local connections, peer authentication will be used instead. - See for details. + See for details. @@ -489,7 +489,7 @@ hostnossl database user Obtain the client's operating system user name from the operating system and check if it matches the requested database user name. This is only available for local connections. - See for details. + See for details. @@ -499,7 +499,7 @@ hostnossl database user Authenticate using an LDAP server. See for details. + linkend="auth-ldap"/> for details. @@ -509,7 +509,7 @@ hostnossl database user Authenticate using a RADIUS server. See for details. + linkend="auth-radius"/> for details. @@ -519,7 +519,7 @@ hostnossl database user Authenticate using SSL client certificates. See - for details. + for details. @@ -530,7 +530,7 @@ hostnossl database user Authenticate using the Pluggable Authentication Modules (PAM) service provided by the operating system. See for details. + linkend="auth-pam"/> for details. @@ -540,7 +540,7 @@ hostnossl database user Authenticate using the BSD Authentication service provided by the - operating system. See for details. + operating system. See for details. @@ -638,7 +638,7 @@ hostnossl database user Some examples of pg_hba.conf entries are shown in - . See the next section for details on the + . See the next section for details on the different authentication methods. @@ -763,7 +763,7 @@ local db1,db2,@demodbs all md5 pg_ident.confpg_ident.conf and is stored in the cluster's data directory. (It is possible to place the map file - elsewhere, however; see the + elsewhere, however; see the configuration parameter.) The ident map file contains lines of the general form: @@ -790,7 +790,7 @@ local db1,db2,@demodbs all md5 If the system-username field starts with a slash (/), the remainder of the field is treated as a regular expression. - (See for details of + (See for details of PostgreSQL's regular expression syntax.) The regular expression can include a single capture, or parenthesized subexpression, which can then be referenced in the database-username @@ -828,8 +828,8 @@ mymap /^(.*)@otherdomain\.com$ guest A pg_ident.conf file that could be used in conjunction with the pg_hba.conf file in is shown in . In this example, anyone + linkend="example-pg-hba.conf"/> is shown in . In this example, anyone logged in to a machine on the 192.168 network that does not have the operating system user name bryanh, ann, or robert 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_socket_permissions (and possibly unix_socket_group) configuration parameters as - described in . Or you + described in . Or you could set the unix_socket_directories configuration parameter to place the socket file in a suitably restricted directory. @@ -965,7 +965,7 @@ omicron bryanh guest1 The md5 method cannot be used with - the feature. + the feature. @@ -998,8 +998,8 @@ omicron bryanh guest1 separate from operating system user passwords. The password for each database user is stored in the pg_authid system catalog. Passwords can be managed with the SQL commands - and - , + and + , e.g., CREATE ROLE foo WITH LOGIN PASSWORD 'secret', or the psql command \password. @@ -1011,7 +1011,7 @@ omicron bryanh guest1 The availability of the different password-based authentication methods depends on how a user's password on the server is encrypted (or hashed, more accurately). This is controlled by the configuration - parameter at the time the + parameter at the time the password is set. If a password was encrypted using the scram-sha-256 setting, then it can be used for the authentication methods scram-sha-256 @@ -1061,7 +1061,7 @@ omicron bryanh guest1 GSSAPI support has to be enabled when PostgreSQL is built; - see for more information. + see for more information. @@ -1072,7 +1072,7 @@ omicron bryanh guest1 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 making the connection from the client using the krbsrvname connection parameter. (See - also .) The installation default can be + also .) The installation default can be changed from the default postgres at build time using ./configure --with-krb-srvnam=whatever. In most environments, @@ -1112,9 +1112,9 @@ omicron bryanh guest1 Make sure that your server keytab file is readable (and preferably only readable, not writable) by the PostgreSQL - server account. (See also .) The location + server account. (See also .) The location of the key file is specified by the configuration + linkend="guc-krb-server-keyfile"/> configuration parameter. The default is /usr/local/pgsql/etc/krb5.keytab (or whatever directory was specified as sysconfdir at build time). @@ -1138,7 +1138,7 @@ omicron bryanh guest1 database user name fred, principal fred@EXAMPLE.COM would be able to connect. To also allow principal fred/users.example.com@EXAMPLE.COM, use a user name - map, as described in . + map, as described in . @@ -1150,7 +1150,7 @@ omicron bryanh guest1 If set to 0, the realm name from the authenticated user principal is stripped off before being passed through the user name mapping - (). This is discouraged and is + (). This is discouraged and is primarily available for backwards compatibility, as it is not secure in multi-realm environments unless krb_realm is also used. It is recommended to @@ -1166,7 +1166,7 @@ omicron bryanh guest1 Allows for mapping between system and database user names. See - for details. For a GSSAPI/Kerberos + for details. For a GSSAPI/Kerberos principal, such as username@EXAMPLE.COM (or, less commonly, username/hostbased@EXAMPLE.COM), the user name used for mapping is @@ -1217,7 +1217,7 @@ omicron bryanh guest1 When using Kerberos authentication, SSPI works the same way - GSSAPI does; see + GSSAPI does; see for details. @@ -1231,7 +1231,7 @@ omicron bryanh guest1 If set to 0, the realm name from the authenticated user principal is stripped off before being passed through the user name mapping - (). This is discouraged and is + (). This is discouraged and is primarily available for backwards compatibility, as it is not secure in multi-realm environments unless krb_realm is also used. It is recommended to @@ -1284,7 +1284,7 @@ omicron bryanh guest1 Allows for mapping between system and database user names. See - for details. For a SSPI/Kerberos + for details. For a SSPI/Kerberos principal, such as username@EXAMPLE.COM (or, less commonly, username/hostbased@EXAMPLE.COM), the user name used for mapping is @@ -1329,7 +1329,7 @@ omicron bryanh guest1 When ident is specified for a local (non-TCP/IP) connection, - peer authentication (see ) will be + peer authentication (see ) will be used instead. @@ -1342,7 +1342,7 @@ omicron bryanh guest1 Allows for mapping between system and database user names. See - for details. + for details. @@ -1415,7 +1415,7 @@ omicron bryanh guest1 Allows for mapping between system and database user names. See - for details. + for details. @@ -1828,7 +1828,7 @@ host ... ldap ldapserver=ldap.example.net ldapbasedn="dc=example, dc=net" ldapse Allows for mapping between system and database user names. See - for details. + for details. diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 7059dd4e5f..3060597011 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -170,7 +170,7 @@ shared_buffers = 128MB postgresql.auto.confpostgresql.auto.conf, which has the same format as postgresql.conf but should never be edited manually. This file holds settings provided through - the command. This file is automatically + the command. This file is automatically read whenever postgresql.conf is, and its settings take effect in the same way. Settings in postgresql.auto.conf override those in postgresql.conf. @@ -191,7 +191,7 @@ shared_buffers = 128MB PostgreSQL provides three SQL commands to establish configuration defaults. - The already-mentioned command + The already-mentioned command provides a SQL-accessible means of changing global defaults; it is functionally equivalent to editing postgresql.conf. In addition, there are two commands that allow setting of defaults @@ -201,14 +201,14 @@ shared_buffers = 128MB - The command allows global + The command allows global settings to be overridden on a per-database basis. - The command allows both global and + The command allows both global and per-database settings to be overridden with user-specific values. @@ -232,7 +232,7 @@ shared_buffers = 128MB - The command allows inspection of the + The command allows inspection of the current value of all parameters. The corresponding function is current_setting(setting_name text). @@ -240,7 +240,7 @@ shared_buffers = 128MB - The command allows modification of the + The command allows modification of the current value of those parameters that can be set locally to a session; it has no effect on other sessions. The corresponding function is @@ -266,7 +266,7 @@ shared_buffers = 128MB - Using on this view, specifically + Using on this view, specifically updating the setting column, is the equivalent of issuing SET commands. For example, the equivalent of @@ -470,7 +470,7 @@ include_dir 'conf.d' already mentioned, PostgreSQL uses two other manually-edited configuration files, which control client authentication (their use is discussed in ). By default, all three + linkend="client-authentication"/>). By default, all three configuration files are stored in the database cluster's data directory. The parameters described in this section allow the configuration files to be placed elsewhere. (Doing so can ease @@ -535,7 +535,7 @@ include_dir 'conf.d' Specifies the configuration file for user name mapping (customarily called pg_ident.conf). This parameter can only be set at server start. - See also . + See also . @@ -625,7 +625,7 @@ include_dir 'conf.d' The default value is localhost, which allows only local TCP/IP loopback connections to be made. While client authentication () allows fine-grained control + linkend="client-authentication"/>) allows fine-grained control over who can access the server, listen_addresses controls which interfaces accept connection attempts, which can help prevent repeated malicious connection requests on @@ -685,7 +685,7 @@ include_dir 'conf.d' Determines the number of connection slots that are reserved for connections by PostgreSQL - superusers. At most + superusers. At most connections can ever be active simultaneously. Whenever the number of active concurrent connections is at least max_connections minus @@ -794,7 +794,7 @@ include_dir 'conf.d' This access control mechanism is independent of the one - described in . + described in . @@ -959,7 +959,7 @@ include_dir 'conf.d' Enables SSL connections. Please read - before using this. + before using this. This parameter can only be set in the postgresql.conf file or on the server command line. The default is off. @@ -1180,8 +1180,8 @@ include_dir 'conf.d' - When a password is specified in or - , this parameter determines the algorithm + When a password is specified in or + , this parameter determines the algorithm to use to encrypt the password. The default value is md5, which stores the password as an MD5 hash (on is also accepted, as alias for md5). Setting this parameter to @@ -1190,7 +1190,7 @@ include_dir 'conf.d' Note that older clients might lack support for the SCRAM authentication mechanism, and hence not work with passwords encrypted with - SCRAM-SHA-256. See for more details. + SCRAM-SHA-256. See for more details. @@ -1228,7 +1228,7 @@ include_dir 'conf.d' Sets the location of the Kerberos server key file. See - + for details. This parameter can only be set in the postgresql.conf file or on the server command line. @@ -1376,7 +1376,7 @@ include_dir 'conf.d' The use of huge pages results in smaller page tables and less CPU time spent on memory management, increasing performance. For more details, - see . + see . @@ -1428,7 +1428,7 @@ include_dir 'conf.d' Sets the maximum number of transactions that can be in the prepared state simultaneously (see ). + linkend="sql-prepare-transaction"/>). Setting this parameter to zero (which is the default) disables the prepared-transaction feature. This parameter can only be set at server start. @@ -1439,7 +1439,7 @@ include_dir 'conf.d' should be set to zero to prevent accidental creation of prepared transactions. If you are using prepared transactions, you will probably want max_prepared_transactions to be at - least as large as , so that every + least as large as , so that every session can have a prepared transaction pending. @@ -1497,10 +1497,10 @@ include_dir 'conf.d' Note that when autovacuum runs, up to - times this memory + times this memory may be allocated, so be careful not to set the default value too high. It may be useful to control for this by separately - setting . + setting . @@ -1515,7 +1515,7 @@ include_dir 'conf.d' Specifies the maximum amount of memory to be used by each autovacuum worker process. It defaults to -1, indicating that - the value of should + the value of should be used instead. The setting has no effect on the behavior of VACUUM when run in other contexts. @@ -1649,8 +1649,8 @@ include_dir 'conf.d' Cost-based Vacuum Delay - During the execution of - and + During the execution of + and commands, the system maintains an internal counter that keeps track of the estimated cost of the various I/O operations that are performed. When the accumulated @@ -1893,7 +1893,7 @@ include_dir 'conf.d' the OS writes data back in larger batches in the background. Often that will result in greatly reduced transaction latency, but there also are some cases, especially with workloads that are bigger than - , but smaller than the OS's page + , but smaller than the OS's page cache, where performance might degrade. This setting may have no effect on some platforms. The valid range is between 0, which disables forced writeback, and @@ -1962,7 +1962,7 @@ include_dir 'conf.d' The default is 1 on supported systems, otherwise 0. This value can be overridden for tables in a particular tablespace by setting the tablespace parameter of the same name (see - ). + ). @@ -1988,8 +1988,8 @@ include_dir 'conf.d' When changing this value, consider also adjusting - and - . + and + . @@ -2005,8 +2005,8 @@ include_dir 'conf.d' Sets the maximum number of workers that can be started by a single Gather or Gather Merge node. Parallel workers are taken from the pool of processes established by - , limited by - . Note that the requested + , limited by + . Note that the requested number of workers may not actually be available at run time. If this occurs, the plan will run with fewer workers than expected, which may be inefficient. The default value is 2. Setting this value to 0 @@ -2020,7 +2020,7 @@ include_dir 'conf.d' system as an additional user session. This should be taken into account when choosing a value for this setting, as well as when configuring other settings that control resource utilization, such - as . Resource limits such as + as . Resource limits such as work_mem are applied individually to each worker, which means the total utilization may be much higher across all processes than it would normally be for any single process. @@ -2031,7 +2031,7 @@ include_dir 'conf.d' For more information on parallel query, see - . + . @@ -2047,9 +2047,9 @@ include_dir 'conf.d' Sets the maximum number of workers that the system can support for parallel queries. The default value is 8. When increasing or decreasing this value, consider also adjusting - . + . Also, note that a setting for this value which is higher than - will have no effect, + will have no effect, since parallel workers are taken from the pool of worker processes established by that setting. @@ -2072,7 +2072,7 @@ include_dir 'conf.d' checkpoint, or when the OS writes data back in larger batches in the background. Often that will result in greatly reduced transaction latency, but there also are some cases, especially with workloads - that are bigger than , but smaller + that are bigger than , but smaller than the OS's page cache, where performance might degrade. This setting may have no effect on some platforms. The valid range is between 0, which disables forced writeback, @@ -2148,7 +2148,7 @@ include_dir 'conf.d' For additional information on tuning these settings, - see . + see . @@ -2176,7 +2176,7 @@ include_dir 'conf.d' In minimal level, WAL-logging of some bulk operations can be safely skipped, which can make those - operations much faster (see ). + operations much faster (see ). Operations in which this optimization can be applied include: CREATE TABLE AS @@ -2188,7 +2188,7 @@ include_dir 'conf.d' But minimal WAL does not contain enough information to reconstruct the data from a base backup and the WAL logs, so replica or higher must be used to enable WAL archiving - () and streaming replication. + () and streaming replication. In logical level, the same information is logged as @@ -2218,7 +2218,7 @@ include_dir 'conf.d' If this parameter is on, the PostgreSQL server will try to make sure that updates are physically written to disk, by issuing fsync() system calls or various - equivalent methods (see ). + equivalent methods (see ). This ensures that the database cluster can recover to a consistent state after an operating system or hardware crash. @@ -2254,7 +2254,7 @@ include_dir 'conf.d' - In many situations, turning off + In many situations, turning off for noncritical transactions can provide much of the potential performance benefit of turning off fsync, without the attendant risks of data corruption. @@ -2264,7 +2264,7 @@ include_dir 'conf.d' fsync can only be set in the postgresql.conf file or on the server command line. If you turn this parameter off, also consider turning off - . + . @@ -2285,8 +2285,8 @@ include_dir 'conf.d' is on. When off, there can be a delay between when success is reported to the client and when the transaction is really guaranteed to be safe against a server crash. (The maximum - delay is three times .) Unlike - , setting this parameter to off + delay is three times .) Unlike + , setting this parameter to off does not create any risk of database inconsistency: an operating system or database crash might result in some recent allegedly-committed transactions being lost, but @@ -2294,10 +2294,10 @@ include_dir 'conf.d' been aborted cleanly. So, turning synchronous_commit off can be a useful alternative when performance is more important than exact certainty about the durability of a transaction. For more - discussion see . + discussion see . - If is non-empty, this + If is non-empty, this parameter also controls whether or not transaction commits will wait for their WAL records to be replicated to the standby server(s). When set to on, commits will wait until replies @@ -2389,7 +2389,7 @@ include_dir 'conf.d' necessary to change this setting or other aspects of your system configuration in order to create a crash-safe configuration or achieve optimal performance. - These aspects are discussed in . + These aspects are discussed in . This parameter can only be set in the postgresql.conf file or on the server command line. @@ -2432,7 +2432,7 @@ include_dir 'conf.d' Turning off this parameter does not affect use of WAL archiving for point-in-time recovery (PITR) - (see ). + (see ). @@ -2480,7 +2480,7 @@ include_dir 'conf.d' When this parameter is on, the PostgreSQL server compresses a full page image written to WAL when - is on or during a base backup. + is on or during a base backup. A compressed page image will be decompressed during WAL replay. The default value is off. Only superusers can change this setting. @@ -2505,7 +2505,7 @@ include_dir 'conf.d' The amount of shared memory used for WAL data that has not yet been written to disk. The default setting of -1 selects a size equal to - 1/32nd (about 3%) of , but not less + 1/32nd (about 3%) of , but not less than 64kB nor more than the size of one WAL segment, typically 16MB. This value can be set manually if the automatic choice is too large or too small, @@ -2682,7 +2682,7 @@ include_dir 'conf.d' checkpoint, or when the OS writes data back in larger batches in the background. Often that will result in greatly reduced transaction latency, but there also are some cases, especially with workloads - that are bigger than , but smaller + that are bigger than , but smaller than the OS's page cache, where performance might degrade. This setting may have no effect on some platforms. The valid range is between 0, which disables forced writeback, @@ -2772,14 +2772,14 @@ include_dir 'conf.d' When archive_mode is enabled, completed WAL segments are sent to archive storage by setting - . In addition to off, + . In addition to off, to disable, there are two modes: on, and always. During normal operation, there is no difference between the two modes, but when set to always the WAL archiver is enabled also during archive recovery or standby mode. In always mode, all files restored from the archive or streamed with streaming replication will be archived (again). See - for details. + for details. archive_mode and archive_command are @@ -2809,7 +2809,7 @@ include_dir 'conf.d' Use %% to embed an actual % character in the command. It is important for the command to return a zero exit status only if it succeeds. For more information see - . + . This parameter can only be set in the postgresql.conf @@ -2836,7 +2836,7 @@ include_dir 'conf.d' - The is only invoked for + The is only invoked for completed WAL segments. Hence, if your server generates little WAL traffic (or has slack periods where it does so), there could be a long delay between the completion of a transaction and its safe @@ -2872,10 +2872,10 @@ include_dir 'conf.d' These settings control the behavior of the built-in streaming replication feature (see - ). Servers will be either a + ). Servers will be either a Master or a Standby server. Masters can send data, while Standby(s) are always receivers of replicated data. When cascading replication - (see ) is used, Standby server(s) + (see ) is used, Standby server(s) can also be senders, as well as receivers. Parameters are mainly for Sending and Standby servers, though some parameters have meaning only on the Master server. Settings may vary @@ -2909,7 +2909,7 @@ include_dir 'conf.d' processes). The default is 10. The value 0 means replication is disabled. WAL sender processes count towards the total number of connections, so the parameter cannot be set higher than - . Abrupt streaming client + . Abrupt streaming client disconnection might cause an orphaned connection slot until a timeout is reached, so this parameter should be set slightly higher than the maximum number of expected clients so disconnected @@ -2930,7 +2930,7 @@ include_dir 'conf.d' Specifies the maximum number of replication slots - (see ) that the server + (see ) that the server can support. The default is 10. This parameter can only be set at server start. wal_level must be set @@ -3021,9 +3021,9 @@ include_dir 'conf.d' These parameters can be set on the master/primary server that is to send replication data to one or more standby servers. Note that in addition to these parameters, - must be set appropriately on the master + must be set appropriately on the master server, and optionally WAL archiving can be enabled as - well (see ). + well (see ). The values of these parameters on standby servers are irrelevant, although you may wish to set them there in preparation for the possibility of a standby becoming the master. @@ -3041,7 +3041,7 @@ include_dir 'conf.d' Specifies a list of standby servers that can support synchronous replication, as described in - . + . There will be one or more active synchronous standbys; transactions waiting for commit will be allowed to proceed after these standby servers confirm receipt of their data. @@ -3148,7 +3148,7 @@ ANY num_sync ( parameter to + parameter to local or off. @@ -3172,7 +3172,7 @@ ANY num_sync ( . This allows + servers, as described in . This allows more time for queries on the standby to complete without incurring conflicts due to early cleanup of rows. However, since the value is measured in terms of number of write transactions occurring on the @@ -3215,7 +3215,7 @@ ANY num_sync ( . + recovery, as described in . The default value is on. This parameter can only be set at server start. It only has effect during archive recovery or in standby mode. @@ -3234,7 +3234,7 @@ ANY num_sync ( . + . max_standby_archive_delay applies when WAL data is being read from WAL archive (and is therefore not current). The default is 30 seconds. Units are milliseconds if not specified. @@ -3265,7 +3265,7 @@ ANY num_sync ( . + . max_standby_streaming_delay applies when WAL data is being received via streaming replication. The default is 30 seconds. Units are milliseconds if not specified. @@ -3484,10 +3484,10 @@ ANY num_sync ( ), - running manually, increasing + constants (see ), + running manually, increasing the value of the configuration parameter, + linkend="guc-default-statistics-target"/> configuration parameter, and increasing the amount of statistics collected for specific columns using ALTER TABLE SET STATISTICS. @@ -3579,7 +3579,7 @@ ANY num_sync ( ). + types (see ). The default is on. @@ -3745,7 +3745,7 @@ ANY num_sync ( ). + (see ). @@ -3762,7 +3762,7 @@ ANY num_sync ( ). + (see ). @@ -3960,7 +3960,7 @@ ANY num_sync ( . + For more information see . @@ -4124,7 +4124,7 @@ ANY num_sync ( . + query planner, refer to . @@ -4180,7 +4180,7 @@ SELECT * FROM parent WHERE key = 2400; - Refer to for + Refer to for more information on using constraint exclusion and partitioning. @@ -4219,13 +4219,13 @@ SELECT * FROM parent WHERE key = 2400; resulting FROM list would have no more than this many items. Smaller values reduce planning time but might yield inferior query plans. The default is eight. - For more information see . + For more information see . - Setting this value to or more + Setting this value to or more may trigger use of the GEQO planner, resulting in non-optimal - plans. See . + plans. See . @@ -4255,13 +4255,13 @@ SELECT * FROM parent WHERE key = 2400; the optimal join order, advanced users can elect to temporarily set this variable to 1, and then specify the join order they desire explicitly. - For more information see . + For more information see . - Setting this value to or more + Setting this value to or more may trigger use of the GEQO planner, resulting in non-optimal - plans. See . + plans. See . @@ -4386,8 +4386,8 @@ SELECT * FROM parent WHERE key = 2400; log entries are output in comma separated value (CSV) format, which is convenient for loading logs into programs. - See for details. - must be enabled to generate + See for details. + must be enabled to generate CSV-format log output. @@ -4420,7 +4420,7 @@ csvlog log/postgresql.csv log_destination. PostgreSQL can log to syslog facilities LOCAL0 through LOCAL7 (see ), but the default + linkend="guc-syslog-facility"/>), but the default syslog configuration on most platforms will discard all such messages. You will need to add something like: @@ -4435,7 +4435,7 @@ local0.* /var/log/postgresql register an event source and its library with the operating system so that the Windows Event Viewer can display event log messages cleanly. - See for details. + See for details. @@ -4522,7 +4522,7 @@ local0.* /var/log/postgresql file names. (Note that if there are any time-zone-dependent %-escapes, the computation is done in the zone specified - by .) + by .) The supported %-escapes are similar to those listed in the Open Group's strftime @@ -4576,7 +4576,7 @@ local0.* /var/log/postgresql server owner can read or write the log files. The other commonly useful setting is 0640, allowing members of the owner's group to read the files. Note however that to make use of such a - setting, you'll need to alter to + setting, you'll need to alter to store the files somewhere outside the cluster data directory. In any case, it's unwise to make the log files world-readable, since they might contain sensitive data. @@ -4897,13 +4897,13 @@ local0.* /var/log/postgresql When using this option together with - , + , the text of statements that are logged because of log_statement will not be repeated in the duration log message. If you are not using syslog, it is recommended that you log the PID or session ID using - + so that you can link the statement message to the later duration message using the process ID or session ID. @@ -4914,7 +4914,7 @@ local0.* /var/log/postgresql - explains the message + explains the message severity levels used by PostgreSQL. If logging output is sent to syslog or Windows' eventlog, the severity levels are translated @@ -5019,7 +5019,7 @@ local0.* /var/log/postgresql It is typically set by an application upon connection to the server. The name will be displayed in the pg_stat_activity view and included in CSV log entries. It can also be included in regular - log entries via the parameter. + log entries via the parameter. Only printable ASCII characters may be used in the application_name value. Other characters will be replaced with question marks (?). @@ -5051,8 +5051,8 @@ local0.* /var/log/postgresql These messages are emitted at LOG message level, so by default they will appear in the server log but will not be sent to the client. You can change that by adjusting - and/or - . + and/or + . These parameters are off by default. @@ -5159,7 +5159,7 @@ local0.* /var/log/postgresql The difference between setting this option and setting - to zero is that + to zero is that exceeding log_min_duration_statement forces the text of the query to be logged, but this option doesn't. Thus, if log_duration is on and @@ -5187,7 +5187,7 @@ local0.* /var/log/postgresql the logging of DETAIL, HINT, QUERY, and CONTEXT error information. VERBOSE output includes the SQLSTATE error - code (see also ) and the source code file name, function name, + code (see also ) and the source code file name, function name, and line number that generated the error. Only superusers can change this setting. @@ -5397,7 +5397,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' Controls whether a log message is produced when a session waits - longer than to acquire a + longer than to acquire a lock. This is useful in determining if lock waits are causing poor performance. The default is off. Only superusers can change this setting. @@ -5459,7 +5459,7 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' Causes each replication command to be logged in the server log. - See for more information about + See for more information about replication command. The default value is off. Only superusers can change this setting. @@ -5496,12 +5496,12 @@ log_line_prefix = '%m [%p] %q%u@%d/%a ' Sets the time zone used for timestamps written in the server log. - Unlike , this value is cluster-wide, + Unlike , this value is cluster-wide, so that all sessions will report timestamps consistently. The built-in default is GMT, but that is typically overridden in postgresql.conf; initdb will install a setting there corresponding to its system environment. - See for more information. + See for more information. This parameter can only be set in the postgresql.conf file or on the server command line. @@ -5641,7 +5641,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; These settings control how process titles of server processes are modified. Process titles are typically viewed using programs like ps or, on Windows, Process Explorer. - See for details. + See for details. @@ -5697,7 +5697,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; When statistics collection is enabled, the data that is produced can be accessed via the pg_stat and pg_statio family of system views. - Refer to for more information. + Refer to for more information. @@ -5766,12 +5766,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; Enables timing of database I/O calls. This parameter is off by default, because it will repeatedly query the operating system for the current time, which may cause significant overhead on some - platforms. You can use the tool to + platforms. You can use the tool to measure the overhead of timing on your system. I/O timing information is - displayed in , in the output of - when the BUFFERS option is - used, and by . Only superusers can + displayed in , in the output of + when the BUFFERS option is + used, and by . Only superusers can change this setting. @@ -5878,10 +5878,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; These settings control the behavior of the autovacuum - feature. Refer to for more information. + feature. Refer to for more information. Note that many of these settings can be overridden on a per-table basis; see . + endterm="sql-createtable-storage-parameters-title"/>. @@ -5896,7 +5896,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; Controls whether the server should run the autovacuum launcher daemon. This is on by default; however, - must also be enabled for + must also be enabled for autovacuum to work. This parameter can only be set in the postgresql.conf file or on the server command line; however, autovacuuming can be @@ -5906,7 +5906,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; Note that even when this parameter is disabled, the system will launch autovacuum processes if necessary to prevent transaction ID wraparound. See for more information. + linkend="vacuum-for-wraparound"/> for more information. @@ -6071,7 +6071,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; This parameter can only be set at server start, but the setting can be reduced for individual tables by changing table storage parameters. - For more information see . + For more information see . @@ -6099,7 +6099,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 400 million multixacts. This parameter can only be set at server start, but the setting can be reduced for individual tables by changing table storage parameters. - For more information see . + For more information see . @@ -6114,7 +6114,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; Specifies the cost delay value that will be used in automatic VACUUM operations. If -1 is specified, the regular - value will be used. + value will be used. The default value is 20 milliseconds. This parameter can only be set in the postgresql.conf file or on the server command line; @@ -6135,7 +6135,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; Specifies the cost limit value that will be used in automatic VACUUM operations. If -1 is specified (which is the default), the regular - value will be used. Note that + value will be used. Note that the value is distributed proportionally among the running autovacuum workers, if there is more than one, so that the sum of the limits for each worker does not exceed the value of this variable. @@ -6230,7 +6230,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; The current effective value of the search path can be examined via the SQL function current_schemas - (see ). + (see ). This is not quite the same as examining the value of search_path, since current_schemas shows how the items @@ -6238,7 +6238,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - For more information on schema handling, see . + For more information on schema handling, see . @@ -6264,7 +6264,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; For more information on row security policies, - see . + see . @@ -6295,7 +6295,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; This variable is not used for temporary tables; for them, - is consulted instead. + is consulted instead. @@ -6306,7 +6306,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; For more information on tablespaces, - see . + see . @@ -6355,7 +6355,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - See also . + See also . @@ -6370,7 +6370,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; This parameter is normally on. When set to off, it disables validation of the function body string during . Disabling validation avoids side + linkend="sql-createfunction"/>. Disabling validation avoids side effects of the validation process and avoids false positives due to problems such as forward references. Set this parameter to off before loading functions on behalf of other @@ -6400,8 +6400,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - Consult and for more information. + Consult and for more information. @@ -6424,7 +6424,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - Consult for more information. + Consult for more information. @@ -6458,7 +6458,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - Consult for more information. + Consult for more information. @@ -6477,7 +6477,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; superuser privilege and results in discarding any previously cached query plans. Possible values are origin (the default), replica and local. - See for + See for more information. @@ -6553,7 +6553,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; longer than the specified duration in milliseconds. This allows any locks held by that session to be released and the connection slot to be reused; it also allows tuples visible only to this transaction to be vacuumed. See - for more details about this. + for more details about this. The default value of 0 disables this feature. @@ -6577,11 +6577,11 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; tuples. The default is 150 million transactions. Although users can set this value anywhere from zero to two billions, VACUUM will silently limit the effective value to 95% of - , so that a + , so that a periodical manual VACUUM has a chance to run before an anti-wraparound autovacuum is launched for the table. For more information see - . + . @@ -6600,10 +6600,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; The default is 50 million transactions. Although users can set this value anywhere from zero to one billion, VACUUM will silently limit the effective value to half - the value of , so + the value of , so that there is not an unreasonably short time between forced autovacuums. For more information see . + linkend="vacuum-for-wraparound"/>. @@ -6624,10 +6624,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; tuples. The default is 150 million multixacts. Although users can set this value anywhere from zero to two billions, VACUUM will silently limit the effective value to 95% of - , so that a + , so that a periodical manual VACUUM has a chance to run before an anti-wraparound is launched for the table. - For more information see . + For more information see . @@ -6646,10 +6646,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; is 5 million multixacts. Although users can set this value anywhere from zero to one billion, VACUUM will silently limit the effective value to half - the value of , + the value of , so that there is not an unreasonably short time between forced autovacuums. - For more information see . + For more information see . @@ -6665,7 +6665,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; Sets the output format for values of type bytea. Valid values are hex (the default) and escape (the traditional PostgreSQL - format). See for more + format). See for more information. The bytea type always accepts both formats on input, regardless of this setting. @@ -6687,7 +6687,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; base64 and hex, which are both defined in the XML Schema standard. The default is base64. For further information about - XML-related functions, see . + XML-related functions, see . @@ -6717,7 +6717,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; Sets whether DOCUMENT or CONTENT is implicit when converting between XML and character string values. See for a description of this. Valid + linkend="datatype-xml"/> for a description of this. Valid values are DOCUMENT and CONTENT. The default is CONTENT. @@ -6748,7 +6748,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; The default is four megabytes (4MB). This setting can be overridden for individual GIN indexes by changing index storage parameters. - See and + See and for more information. @@ -6780,7 +6780,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; and European are synonyms for DMY; the keywords US, NonEuro, and NonEuropean are synonyms for MDY. See - for more information. The + for more information. The built-in default is ISO, MDY, but initdb will initialize the configuration file with a setting that corresponds to the @@ -6802,7 +6802,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; output matching SQL standard interval literals. The value postgres (which is the default) will produce output matching PostgreSQL releases prior to 8.4 - when the + when the parameter was set to ISO. The value postgres_verbose will produce output matching PostgreSQL releases prior to 8.4 @@ -6815,7 +6815,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; The IntervalStyle parameter also affects the interpretation of ambiguous interval input. See - for more information. + for more information. @@ -6833,7 +6833,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; The built-in default is GMT, but that is typically overridden in postgresql.conf; initdb will install a setting there corresponding to its system environment. - See for more information. + See for more information. @@ -6852,7 +6852,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; which is a collection that works in most of the world; there are also 'Australia' and 'India', and other collections can be defined for a particular installation. - See for more information. + See for more information. @@ -6880,7 +6880,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; partially-significant digits; this is especially useful for dumping float data that needs to be restored exactly. Or it can be set negative to suppress unwanted digits. - See also . + See also . @@ -6897,7 +6897,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; Sets the client-side encoding (character set). The default is to use the database encoding. The character sets supported by the PostgreSQL - server are described in . + server are described in . @@ -6911,7 +6911,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; Sets the language in which messages are displayed. Acceptable - values are system-dependent; see for + values are system-dependent; see for more information. If this variable is set to the empty string (which is the default) then the value is inherited from the execution environment of the server in a system-dependent way. @@ -6945,7 +6945,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; Sets the locale to use for formatting monetary amounts, for example with the to_char family of functions. Acceptable values are system-dependent; see for more information. If this variable is + linkend="locale"/> for more information. If this variable is set to the empty string (which is the default) then the value is inherited from the execution environment of the server in a system-dependent way. @@ -6964,7 +6964,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; Sets the locale to use for formatting numbers, for example with the to_char family of functions. Acceptable values are system-dependent; see for more information. If this variable is + linkend="locale"/> for more information. If this variable is set to the empty string (which is the default) then the value is inherited from the execution environment of the server in a system-dependent way. @@ -6983,7 +6983,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; Sets the locale to use for formatting dates and times, for example with the to_char family of functions. Acceptable values are system-dependent; see for more information. If this variable is + linkend="locale"/> for more information. If this variable is set to the empty string (which is the default) then the value is inherited from the execution environment of the server in a system-dependent way. @@ -7002,7 +7002,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; Selects the text search configuration that is used by those variants of the text search functions that do not have an explicit argument specifying the configuration. - See for further information. + See for further information. The built-in default is pg_catalog.simple, but initdb will initialize the configuration file with a setting that corresponds to the @@ -7067,7 +7067,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; This variable specifies one or more shared libraries that are to be preloaded at connection start. It contains a comma-separated list of library names, where each name - is interpreted as for the command. + is interpreted as for the command. Whitespace between entries is ignored; surround a library name with double quotes if you need to include whitespace or commas in the name. The parameter value only takes effect at the start of the connection. @@ -7101,7 +7101,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; However, unless a module is specifically designed to be used in this way by non-superusers, this is usually not the right setting to use. Look - at instead. + at instead. @@ -7118,7 +7118,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; This variable specifies one or more shared libraries that are to be preloaded at connection start. It contains a comma-separated list of library names, where each name - is interpreted as for the command. + is interpreted as for the command. Whitespace between entries is ignored; surround a library name with double quotes if you need to include whitespace or commas in the name. The parameter value only takes effect at the start of the connection. @@ -7132,7 +7132,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; performance-measurement libraries to be loaded into specific sessions without an explicit LOAD command being given. For - example, could be enabled for all + example, could be enabled for all sessions under a given user name by setting this parameter with ALTER ROLE SET. Also, this parameter can be changed without restarting the server (but changes only take effect when a new @@ -7141,7 +7141,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; - Unlike , there is no large + Unlike , there is no large performance advantage to loading a library at session start rather than when it is first used. There is some advantage, however, when connection pooling is used. @@ -7160,7 +7160,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; This variable specifies one or more shared libraries to be preloaded at server start. It contains a comma-separated list of library names, where each name - is interpreted as for the command. + is interpreted as for the command. Whitespace between entries is ignored; surround a library name with double quotes if you need to include whitespace or commas in the name. This parameter can only be set at server start. If a specified @@ -7183,7 +7183,7 @@ SET XML OPTION { DOCUMENT | CONTENT }; parameter is recommended only for libraries that will be used in most sessions. Also, changing this parameter requires a server restart, so this is not the right setting to use for short-term debugging tasks, - say. Use for that + say. Use for that instead. @@ -7269,7 +7269,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' Soft upper limit of the size of the set returned by GIN index scans. For more - information see . + information see . @@ -7317,7 +7317,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - When is set, + When is set, this parameter also determines the length of time to wait before a log message is issued about the lock wait. If you are trying to investigate locking delays you might want to set a shorter than @@ -7336,8 +7336,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' The shared lock table tracks locks on max_locks_per_transaction * ( + ) objects (e.g., tables); + linkend="guc-max-connections"/> + ) objects (e.g., tables); hence, no more than this many distinct objects can be locked at any one time. This parameter controls the average number of object locks allocated for each transaction; individual transactions @@ -7368,8 +7368,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' The shared predicate lock table tracks locks on max_pred_locks_per_transaction * ( + ) objects (e.g., tables); + linkend="guc-max-connections"/> + ) objects (e.g., tables); hence, no more than this many distinct objects can be locked at any one time. This parameter controls the average number of object locks allocated for each transaction; individual transactions @@ -7396,7 +7396,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' predicate-locked before the lock is promoted to covering the whole relation. Values greater than or equal to zero mean an absolute limit, while negative values - mean divided by + mean divided by the absolute value of this setting. The default is -2, which keeps the behavior from previous versions of PostgreSQL. This parameter can only be set in the postgresql.conf @@ -7589,7 +7589,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - See for more information. + See for more information. @@ -7607,7 +7607,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' output of EXPLAIN as well as the results of functions like pg_get_viewdef. See also the option of - and . + and . @@ -7630,7 +7630,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' parameter to determine how string literals will be processed. The presence of this parameter can also be taken as an indication that the escape string syntax (E'...') is supported. - Escape string syntax () + Escape string syntax () should be used if an application desires backslashes to be treated as escape characters. @@ -7710,7 +7710,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - Refer to for related information. + Refer to for related information. @@ -7788,9 +7788,9 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' Reports the size of a disk block. It is determined by the value of BLCKSZ when building the server. The default value is 8192 bytes. The meaning of some configuration - variables (such as ) is + variables (such as ) is influenced by block_size. See for information. + linkend="runtime-config-resource"/> for information. @@ -7804,7 +7804,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' Reports whether data checksums are enabled for this cluster. - See for more information. + See for more information. @@ -7853,7 +7853,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' Reports the locale in which sorting of textual data is done. - See for more information. + See for more information. This value is determined when a database is created. @@ -7868,7 +7868,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' Reports the locale that determines character classifications. - See for more information. + See for more information. This value is determined when a database is created. Ordinarily this will be the same as lc_collate, but for special applications it might be set differently. @@ -7953,7 +7953,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' Reports the database encoding (character set). It is determined when the database is created. Ordinarily, clients need only be concerned with the value of . + linkend="guc-client-encoding"/>. @@ -8012,7 +8012,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' Reports the number of blocks (pages) in a WAL segment file. The total size of a WAL segment file in bytes is equal to wal_segment_size multiplied by wal_block_size; - by default this is 16MB. See for + by default this is 16MB. See for more information. @@ -8140,8 +8140,8 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' Generates a great amount of debugging output for the LISTEN and NOTIFY - commands. or - must be + commands. or + must be DEBUG1 or lower to send this output to the client or server logs, respectively. @@ -8158,7 +8158,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' Enables logging of recovery-related debugging output that otherwise would not be logged. This parameter allows the user to override the - normal setting of , but only for + normal setting of , but only for specific messages. This is intended for use in debugging Hot Standby. Valid values are DEBUG5, DEBUG4, DEBUG3, DEBUG2, DEBUG1, and @@ -8401,7 +8401,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - Only has effect if are enabled. + Only has effect if are enabled. Detection of a checksum failure during a read normally causes @@ -8452,7 +8452,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) For convenience there are also single letter command-line option switches available for some parameters. They are described in - . Some of these + . Some of these options exist for historical reasons, and their presence as a single-letter option does not necessarily indicate an endorsement to use the option heavily. diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml index 7dd203e9cd..0622227bee 100644 --- a/doc/src/sgml/contrib.sgml +++ b/doc/src/sgml/contrib.sgml @@ -16,14 +16,14 @@ This appendix covers extensions and other server plug-in modules found in - contrib. covers utility + contrib. covers utility programs. When building from the source distribution, these components are not built automatically, unless you build the "world" target - (see ). + (see ). You can build and install all of them by running: make @@ -55,7 +55,7 @@ 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. In PostgreSQL 9.1 and later, this is done by executing - a command. In a fresh database, + a command. In a fresh database, you can simply do @@ -89,16 +89,16 @@ CREATE EXTENSION module_name FROM unpackaged; This will update the pre-9.1 objects of the module into a proper extension object. Future updates to the module will be - managed by . + managed by . For more information about extension updates, see - . + . Note, however, that some of these modules are not extensions in this sense, but are loaded into the server in some other way, for instance by way of - . See the documentation of each + . See the documentation of each module for details. @@ -163,7 +163,7 @@ pages. This appendix and the previous one contain information regarding the modules that can be found in the contrib directory of the - PostgreSQL distribution. See for + PostgreSQL distribution. See for more information about the contrib section in general and server extensions and plug-ins found in contrib specifically. @@ -184,7 +184,7 @@ pages. This section covers PostgreSQL client applications in contrib. They can be run from anywhere, independent of where the database server resides. See - also for information about client + also for information about client applications that part of the core PostgreSQL distribution. @@ -200,7 +200,7 @@ pages. This section covers PostgreSQL server-related applications in contrib. They are typically run on the host where the database server resides. See also for information about server applications that + linkend="reference-server"/> for information about server applications that part of the core PostgreSQL distribution. diff --git a/doc/src/sgml/cube.sgml b/doc/src/sgml/cube.sgml index 46d8e4eb8f..b995dc7e2a 100644 --- a/doc/src/sgml/cube.sgml +++ b/doc/src/sgml/cube.sgml @@ -16,7 +16,7 @@ Syntax - shows the valid external + shows the valid external representations for the cube type. x, y, etc. denote floating-point numbers. @@ -106,7 +106,7 @@ Usage - shows the operators provided for + shows the operators provided for type cube. @@ -268,7 +268,7 @@ SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5; - shows the available functions. + shows the available functions.
diff --git a/doc/src/sgml/custom-scan.sgml b/doc/src/sgml/custom-scan.sgml index a46641674f..24631f5f40 100644 --- a/doc/src/sgml/custom-scan.sgml +++ b/doc/src/sgml/custom-scan.sgml @@ -123,7 +123,7 @@ Plan *(*PlanCustomPath) (PlannerInfo *root, Convert a custom path to a finished plan. The return value will generally be a CustomScan object, which the callback must allocate and - initialize. See for more details. + initialize. See for more details. diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 3d46098263..9aa9b28f3e 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -16,11 +16,11 @@ PostgreSQL has a rich set of native data types available to users. Users can add new types to PostgreSQL using the command. + linkend="sql-createtype"/> command. - shows all the built-in general-purpose data + shows all the built-in general-purpose data types. Most of the alternative names listed in the Aliases column are the names used internally by PostgreSQL for historical reasons. In @@ -336,7 +336,7 @@ Numeric types consist of two-, four-, and eight-byte integers, four- and eight-byte floating-point numbers, and selectable-precision - decimals. lists the + decimals. lists the available types. @@ -424,9 +424,9 @@ The syntax of constants for the numeric types is described in - . The numeric types have a + . The numeric types have a full set of corresponding arithmetic operators and - functions. Refer to for more + functions. Refer to for more information. The following sections describe the types in detail. @@ -559,7 +559,7 @@ NUMERIC The maximum allowed precision when explicitly specified in the type declaration is 1000; NUMERIC without a specified precision is subject to the limits described in . + linkend="datatype-numeric-table"/>. @@ -728,7 +728,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; - The setting controls the + The setting controls the number of extra significant digits included when a floating point value is converted to text for output. With the default value of 0, the output is the same on every platform @@ -841,7 +841,7 @@ FROM generate_series(-3.5, 3.5, 1) as x; This section describes a PostgreSQL-specific way to create an autoincrementing column. Another way is to use the SQL-standard - identity column feature, described at . + identity column feature, described at . @@ -888,7 +888,7 @@ ALTER SEQUENCE tablename_nextval() in + See nextval() in for details. @@ -929,8 +929,8 @@ ALTER SEQUENCE tablename_ The money type stores a currency amount with a fixed fractional precision; see . The fractional precision is - determined by the database's setting. + linkend="datatype-money-table"/>. The fractional precision is + determined by the database's setting. The range shown in the table assumes there are two fractional digits. Input is accepted in a variety of formats, including integer and floating-point literals, as well as typical @@ -1063,7 +1063,7 @@ SELECT '52093.89'::money::numeric::float8;
- shows the + shows the general-purpose character types available in PostgreSQL. @@ -1166,12 +1166,12 @@ SELECT '52093.89'::money::numeric::float8; - Refer to for information about - the syntax of string literals, and to + Refer to for information about + the syntax of string literals, and to for information about available operators and functions. The database character set determines the character set used to store textual values; for more information on character set support, - refer to . + refer to . @@ -1180,7 +1180,7 @@ SELECT '52093.89'::money::numeric::float8; CREATE TABLE test1 (a character(4)); INSERT INTO test1 VALUES ('ok'); -SELECT a, char_length(a) FROM test1; -- +SELECT a, char_length(a) FROM test1; -- a | char_length ------+------------- @@ -1206,7 +1206,7 @@ SELECT b, char_length(b) FROM test2; The char_length function is discussed in - . + . @@ -1215,7 +1215,7 @@ SELECT b, char_length(b) FROM test2; There are two other fixed-length character types in PostgreSQL, shown in . The name + linkend="datatype-character-special-table"/>. The name type exists only for the storage of identifiers 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 @@ -1269,7 +1269,7 @@ SELECT b, char_length(b) FROM test2; The bytea data type allows storage of binary strings; - see . + see . @@ -1313,7 +1313,7 @@ SELECT b, char_length(b) FROM test2; input and output: PostgreSQL's historical escape format, and hex format. Both of these are always accepted on input. The output format depends - on the configuration parameter ; + on the configuration parameter ; the default is hex. (Note that the hex format was introduced in PostgreSQL 9.0; earlier versions and some tools don't understand it.) @@ -1384,7 +1384,7 @@ SELECT E'\\xDEADBEEF'; literal using escape string syntax). Backslash itself (octet value 92) can alternatively be represented by double backslashes. - + shows the characters that must be escaped, and gives the alternative escape sequences where applicable. @@ -1443,14 +1443,14 @@ SELECT E'\\xDEADBEEF'; The requirement to escape non-printable octets 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 - in was exactly one octet in + in was exactly one octet in length, even though the output representation is sometimes more than one character. The reason multiple backslashes are required, as shown - in , is that an input + in , is that an input string written as a string literal must pass through two parse phases in the PostgreSQL server. 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 single-quote character is not treated specially by bytea, so it follows the normal rules for string literals. (See also - .) + .) @@ -1477,7 +1477,7 @@ SELECT E'\\xDEADBEEF'; Most printable octets are represented by their standard representation in the client character set. The octet with decimal value 92 (backslash) is doubled in the output. - Details are in . + Details are in .
@@ -1571,12 +1571,12 @@ SELECT E'\\xDEADBEEF'; PostgreSQL supports the full set of SQL date and time types, shown in . The operations available + linkend="datatype-datetime-table"/>. The operations available on these data types are described in - . + . Dates are counted according to the Gregorian calendar, even in years before that calendar was introduced (see for more information). + linkend="datetime-units-history"/> for more information).
@@ -1716,7 +1716,7 @@ MINUTE TO SECOND traditional POSTGRES, and others. For some formats, ordering of day, month, and year in date input is ambiguous and there is support for specifying the expected - ordering of these fields. Set the parameter + ordering of these fields. Set the parameter to MDY to select month-day-year interpretation, DMY to select day-month-year interpretation, or YMD to select year-month-day interpretation. @@ -1726,7 +1726,7 @@ MINUTE TO SECOND PostgreSQL is more flexible in handling date/time input than the SQL standard requires. - See + See for the exact parsing rules of date/time input and for the recognized text fields including months, days of the week, and time zones. @@ -1735,7 +1735,7 @@ MINUTE TO SECOND Remember that any date or time literal input needs to be enclosed in single quotes, like text strings. Refer to - for more + for more information. SQL requires the following syntax @@ -1759,7 +1759,7 @@ MINUTE TO SECOND - shows some possible + shows some possible inputs for the date type. @@ -1872,8 +1872,8 @@ MINUTE TO SECOND Valid input for these types consists of a time of day followed by an optional time zone. (See - and .) If a time zone is + linkend="datatype-datetime-time-table"/> + and .) If a time zone is specified in the input for time without time zone, 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 @@ -1993,7 +1993,7 @@ MINUTE TO SECOND
- Refer to for more information on how + Refer to for more information on how to specify time zones. @@ -2074,7 +2074,7 @@ January 8 04:05:06 1999 PST 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, then it is assumed to be in the time zone indicated by the system's - parameter, and is converted to UTC using the + parameter, and is converted to UTC using the offset for the timezone zone. @@ -2084,7 +2084,7 @@ January 8 04:05:06 1999 PST current timezone zone, and displayed as local time in that zone. To see the time in another time zone, either change timezone or use the AT TIME ZONE construct - (see ). + (see ). @@ -2112,7 +2112,7 @@ January 8 04:05:06 1999 PST PostgreSQL supports several special date/time input values for convenience, as shown in . The values + linkend="datatype-datetime-special-table"/>. The values infinity and -infinity are specially represented inside the system and will be displayed unchanged; but the others are simply notational shorthands @@ -2186,7 +2186,7 @@ January 8 04:05:06 1999 PST CURRENT_TIMESTAMP, LOCALTIME, LOCALTIMESTAMP. The latter four accept an optional subsecond precision specification. (See .) Note that these are + linkend="functions-datetime-current"/>.) Note that these are SQL functions and are not recognized in data input strings. @@ -2218,7 +2218,7 @@ January 8 04:05:06 1999 PST SQL standard requires the use of the ISO 8601 format. The name of the SQL output format is a historical accident.) shows examples of each + linkend="datatype-datetime-output-table"/> shows examples of each output style. The output of the date and time types is generally only the date or time part in accordance with the given examples. However, the @@ -2275,9 +2275,9 @@ January 8 04:05:06 1999 PST In the SQL and POSTGRES styles, day appears before month if DMY field ordering has been specified, otherwise month appears before day. - (See + (See for how this setting also affects interpretation of input values.) - shows examples. + shows examples. @@ -2313,7 +2313,7 @@ January 8 04:05:06 1999 PST The date/time style can be selected by the user using the SET datestyle command, the parameter in the + linkend="guc-datestyle"/> parameter in the postgresql.conf configuration file, or the PGDATESTYLE environment variable on the server or client. @@ -2321,7 +2321,7 @@ January 8 04:05:06 1999 PST The formatting function to_char - (see ) is also available as + (see ) is also available as a more flexible way to format date/time output. @@ -2391,7 +2391,7 @@ January 8 04:05:06 1999 PST All timezone-aware dates and times are stored internally in UTC. They are converted to local time - in the zone specified by the configuration + in the zone specified by the configuration parameter before being displayed to the client. @@ -2404,7 +2404,7 @@ January 8 04:05:06 1999 PST A full time zone name, for example America/New_York. The recognized time zone names are listed in the pg_timezone_names view (see ). + linkend="view-pg-timezone-names"/>). PostgreSQL uses the widely-used IANA time zone data for this purpose, so the same time zone 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 savings transition-date rules as well. The recognized abbreviations are listed in the pg_timezone_abbrevs view (see ). You cannot set the - configuration parameters or - to a time + linkend="view-pg-timezone-abbrevs"/>). You cannot set the + configuration parameters or + to a time zone abbreviation, but you can use abbreviations in date/time input values and with the AT TIME ZONE operator. @@ -2499,13 +2499,13 @@ January 8 04:05:06 1999 PST they are obtained from configuration files stored under .../share/timezone/ and .../share/timezonesets/ of the installation directory - (see ). + (see ). - The configuration parameter can + The configuration parameter can be set in the file postgresql.conf, or in any of the - other standard ways described in . + other standard ways described in . There are also some special ways to set it: @@ -2556,7 +2556,7 @@ January 8 04:05:06 1999 PST of the different units are implicitly added with appropriate sign accounting. ago negates all the fields. This syntax is also used for interval output, if - is set to + is set to postgres_verbose. @@ -2582,7 +2582,7 @@ P quantityunit The string must start with a P, and may include a T that introduces the time-of-day units. The available unit abbreviations are given in . Units may be + linkend="datatype-interval-iso8601-units"/>. Units may be omitted, and may be specified in any order, but units smaller than a day must appear after T. In particular, the meaning of M depends on whether it is before or after @@ -2696,7 +2696,7 @@ P years-months- - shows some examples + shows some examples of valid interval input. @@ -2751,7 +2751,7 @@ P years-months- postgres_verbose, or iso_8601, using the command SET intervalstyle. The default is the postgres format. - shows examples of each + shows examples of each output style. @@ -2768,7 +2768,7 @@ P years-months- The output of the postgres style matches the output of PostgreSQL releases prior to 8.4 when the - parameter was set to ISO. + parameter was set to ISO. @@ -2846,7 +2846,7 @@ P years-months- PostgreSQL provides the standard SQL type boolean; - see . + see . The boolean type can have several states: true, false, and a third state, unknown, which is represented by the @@ -2902,7 +2902,7 @@ P years-months- - shows that + shows that boolean values are output using the letters t and f. @@ -2954,7 +2954,7 @@ SELECT * FROM test1 WHERE a; Enum types are created using the command, + linkend="sql-createtype"/> command, for example: @@ -3087,7 +3087,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays Geometric data types represent two-dimensional spatial - objects. shows the geometric + objects. shows the geometric types available in PostgreSQL. @@ -3158,7 +3158,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays A rich set of functions and operators is available to perform various geometric operations such as scaling, translation, rotation, and determining - intersections. They are explained in . + intersections. They are explained in . @@ -3410,11 +3410,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays PostgreSQL offers data types to store IPv4, IPv6, and MAC - addresses, as shown in . It + addresses, as shown in . It is better to use these types instead of plain text types to store network addresses, because these types offer input error checking and specialized - operators and functions (see ). + operators and functions (see ).
@@ -3526,7 +3526,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays - shows some examples. + shows some examples.
@@ -3809,10 +3809,10 @@ SELECT macaddr8_set7bit('08:00:2b:01:02:03'); Refer to for information about the syntax + linkend="sql-syntax-bit-strings"/> for information about the syntax of bit string constants. Bit-logical operators and string manipulation functions are available; see . + linkend="functions-bitstring"/>. @@ -3840,7 +3840,7 @@ SELECT * FROM test; 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 (but long values may be compressed or moved out-of-line, as explained - in for character strings). + in for character strings). @@ -3865,8 +3865,8 @@ SELECT * FROM test; The tsvector type represents a document in a form optimized for text search; the tsquery type similarly represents a text query. - provides a detailed explanation of this - facility, and summarizes the + provides a detailed explanation of this + facility, and summarizes the related functions and operators. @@ -3881,7 +3881,7 @@ SELECT * FROM test; A tsvector value is a sorted list of distinct lexemes, which are words that have been normalized to merge different variants of the same word - (see for details). Sorting and + (see for details). Sorting and duplicate-elimination are done automatically during input, as shown in this example: @@ -3975,7 +3975,7 @@ SELECT to_tsvector('english', 'The Fat Rats'); 'fat':2 'rat':3 - Again, see for more detail. + Again, see for more detail. @@ -4140,9 +4140,9 @@ a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11 functions for UUIDs, but the core database does not include any function for generating UUIDs, because no single algorithm is well suited for every application. The module + linkend="uuid-ossp"/> module provides functions that implement several standard algorithms. - The module also provides a generation + The module also provides a generation function for random UUIDs. Alternatively, UUIDs could be generated by client applications or 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 text field is that it checks the input values for well-formedness, and there are support functions to perform type-safe operations on it; see . Use of this data type requires the + linkend="functions-xml"/>. Use of this data type requires the installation to have been built with configure --with-libxml. @@ -4267,7 +4267,7 @@ SET xmloption TO { DOCUMENT | CONTENT }; results to the client (which is the normal mode), PostgreSQL converts all character data passed between the client and the server and vice versa to the character encoding of the respective - end; see . This includes string + end; see . This includes string representations of XML values, such as in the above examples. This would ordinarily mean that encoding declarations contained in XML data can become invalid as the character data is converted @@ -4408,7 +4408,7 @@ INSERT INTO mytable VALUES(-1); -- fails - For additional information see . + For additional information see . @@ -4473,14 +4473,14 @@ INSERT INTO mytable VALUES(-1); -- fails PostgreSQL as primary keys for various system tables. OIDs are not added to user-created tables, unless WITH OIDS is specified when the table is - created, or the + created, or the configuration variable is enabled. Type oid represents an object identifier. There are also several alias types for oid: regproc, regprocedure, regoper, regoperator, regclass, regtype, regrole, regnamespace, regconfig, and regdictionary. - shows an overview. + shows an overview. @@ -4677,7 +4677,7 @@ SELECT * FROM pg_attribute (The system columns are further explained in .) + linkend="ddl-system-columns"/>.) @@ -4795,7 +4795,7 @@ SELECT * FROM pg_attribute useful in situations where a function's behavior does not correspond to simply taking or returning a value of a specific SQL data type. lists the existing + linkend="datatype-pseudotypes-table"/> lists the existing pseudo-types. @@ -4818,33 +4818,33 @@ SELECT * FROM pg_attribute anyelement Indicates that a function accepts any data type - (see ). + (see ). anyarray Indicates that a function accepts any array data type - (see ). + (see ). anynonarray Indicates that a function accepts any non-array data type - (see ). + (see ). anyenum Indicates that a function accepts any enum data type - (see and - ). + (see and + ). anyrange Indicates that a function accepts any range data type - (see and - ). + (see and + ). diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml index a533bbf8d2..d269aa4cc5 100644 --- a/doc/src/sgml/datetime.sgml +++ b/doc/src/sgml/datetime.sgml @@ -180,7 +180,7 @@ Date/Time Key Words - shows the tokens that are + shows the tokens that are recognized as names of months. @@ -247,7 +247,7 @@
- shows the tokens that are + shows the tokens that are recognized as names of days of the week. @@ -294,7 +294,7 @@ - shows the tokens that serve + shows the tokens that serve various modifier purposes. @@ -349,7 +349,7 @@ Since timezone abbreviations are not well standardized, PostgreSQL provides a means to customize the set of abbreviations accepted by the server. The - run-time parameter + run-time parameter determines the active set of abbreviations. While this parameter can be altered by any database user, the possible values for it are under the control of the database administrator — they diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml index 12928e8bd3..4c07f886aa 100644 --- a/doc/src/sgml/dblink.sgml +++ b/doc/src/sgml/dblink.sgml @@ -14,7 +14,7 @@ - See also , which provides roughly the same + See also , which provides roughly the same functionality using a more modern and standards-compliant infrastructure. @@ -58,8 +58,8 @@ dblink_connect(text connname, text connstr) returns text server. It is recommended to use the foreign-data wrapper dblink_fdw when defining the foreign server. See the example below, as well as - and - . + and + . @@ -84,7 +84,7 @@ dblink_connect(text connname, text connstr) returns text libpq-style connection info string, for example hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres password=mypasswd. - For details see . + For details see . Alternatively, the name of a foreign server. @@ -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. To receive notifications via dblink, LISTEN must first be issued, using dblink_exec. - For details see and . + For details see and . diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml index daba66c187..e6f50ec819 100644 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -39,7 +39,7 @@ 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, unless sorting is explicitly requested. This is covered in . 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 identical rows in a table. This is a consequence of the 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 define their own data types. Most built-in data types have obvious names and semantics, so we defer a detailed explanation to . Some of the frequently used data types are + linkend="datatype"/>. Some of the frequently used data types are integer for whole numbers, numeric for possibly fractional numbers, text for character strings, date for dates, time for @@ -79,7 +79,7 @@ To create a table, you use the aptly named command. + linkend="sql-createtable"/> command. 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 example: @@ -95,7 +95,7 @@ CREATE TABLE my_first_table ( text; the second column has the name second_column and the type integer. The table and column names follow the identifier syntax explained - in . The type names are + in . The type names are usually also identifiers, but there are some exceptions. Note that the column list is comma-separated and surrounded by parentheses. @@ -139,7 +139,7 @@ CREATE TABLE products ( If you no longer need a table, you can remove it using the command. + linkend="sql-droptable"/> command. For example: DROP TABLE my_first_table; @@ -155,7 +155,7 @@ DROP TABLE products; If you need to modify a table that already exists, see later in this chapter. + linkend="ddl-alter"/> later in this chapter. @@ -163,7 +163,7 @@ DROP TABLE products; tables. The remainder of this chapter is concerned with adding features to the table definition to ensure data integrity, security, or convenience. If you are eager to fill your tables with - data now you can skip ahead to and read the + data now you can skip ahead to and read the rest of this chapter later. @@ -181,7 +181,7 @@ DROP TABLE products; columns will be filled with their respective default values. A data manipulation command can also request explicitly that a column be set to its default value, without having to know what that value is. - (Details about data manipulation commands are in .) + (Details about data manipulation commands are in .) @@ -220,7 +220,7 @@ CREATE TABLE products ( where the nextval() function supplies successive values from a sequence object (see ). This arrangement is sufficiently common + linkend="functions-sequence"/>). This arrangement is sufficiently common that there's a special shorthand for it: CREATE TABLE products ( @@ -229,7 +229,7 @@ CREATE TABLE products ( ); The SERIAL shorthand is discussed further in . + linkend="datatype-serial"/>. @@ -876,9 +876,9 @@ CREATE TABLE order_items ( More information about updating and deleting data is in . Also see the description of foreign key constraint + linkend="dml"/>. Also see the description of foreign key constraint syntax in the reference documentation for - . + . @@ -948,10 +948,10 @@ CREATE TABLE circles ( The object identifier (object ID) of a row. This column is only present if the table was created using WITH - OIDS, or if the + OIDS, or if the configuration variable was set at the time. This column is of type oid (same name as the column); see for more information about the type. + linkend="datatype-oid"/> for more information about the type. @@ -966,7 +966,7 @@ CREATE TABLE circles ( The OID of the table containing this row. This column is particularly handy for queries that select from inheritance - hierarchies (see ), since without it, + hierarchies (see ), since without it, it's difficult to tell which individual table a row came from. The tableoid can be joined against the oid column of @@ -1100,7 +1100,7 @@ CREATE TABLE circles ( Transaction identifiers are also 32-bit quantities. In a long-lived database it is possible for transaction IDs to wrap around. This is not a fatal problem given appropriate maintenance - procedures; see for details. It is + procedures; see for details. It is unwise, however, to depend on the uniqueness of transaction IDs over the long term (more than one billion transactions). @@ -1167,7 +1167,7 @@ CREATE TABLE circles ( All these actions are performed using the - + command, whose reference page contains details beyond those given here. @@ -1238,7 +1238,7 @@ ALTER TABLE products DROP COLUMN description; ALTER TABLE products DROP COLUMN description CASCADE; - See for a description of the general + See for a description of the general mechanism behind this. @@ -1446,7 +1446,7 @@ ALTER TABLE products RENAME TO items; object vary depending on the object's type (table, function, etc). For complete information on the different types of privileges supported by PostgreSQL, refer to the - reference + reference page. The following sections and chapters will also show you how those privileges are used. @@ -1459,7 +1459,7 @@ ALTER TABLE products RENAME TO items; An object can be assigned to a new owner with an ALTER command of the appropriate kind for the object, e.g. . 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 of the object (or a member of the owning role) and a member of the new 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, group roles can be set up to help manage privileges when there are many users of a database — for details see - . + . @@ -1506,8 +1506,8 @@ REVOKE ALL ON accounts FROM PUBLIC; the right to grant it in turn to others. If the grant option is subsequently revoked then all who received the privilege from that recipient (directly or through a chain of grants) will lose the - privilege. For details see the and - reference pages. + privilege. For details see the and + reference pages. @@ -1524,7 +1524,7 @@ REVOKE ALL ON accounts FROM PUBLIC; In addition to the SQL-standard privilege - system available through , + system available through , tables can have row security policies that restrict, on a per-user basis, which rows can be returned by normal queries or inserted, updated, or deleted by data modification commands. @@ -1584,11 +1584,11 @@ REVOKE ALL ON accounts FROM PUBLIC; - Policies are created using the - command, altered using the command, - and dropped using the command. To + Policies are created using the + command, altered using the command, + and dropped using the command. To enable and disable row security for a given table, use the - command. + command. @@ -1829,7 +1829,7 @@ UPDATE 0 not being applied. For example, when taking a backup, it could be disastrous if row security silently caused some rows to be omitted from the backup. In such a situation, you can set the - configuration parameter + configuration parameter to off. This does not in itself bypass row security; 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 @@ -1951,8 +1951,8 @@ SELECT * FROM information WHERE group_id = 2 FOR UPDATE; - For additional details see - and . + For additional details see + and . @@ -2034,7 +2034,7 @@ SELECT * FROM information WHERE group_id = 2 FOR UPDATE; - To create a schema, use the + To create a schema, use the command. Give the schema a name of your choice. For example: @@ -2099,7 +2099,7 @@ DROP SCHEMA myschema; DROP SCHEMA myschema CASCADE; - See for a description of the general + See for a description of the general mechanism behind this. @@ -2112,7 +2112,7 @@ CREATE SCHEMA schema_name AUTHORIZATION You can even omit the schema name, in which case the schema name will be the same as the user name. See for how this can be useful. + linkend="ddl-schemas-patterns"/> for how this can be useful. @@ -2242,7 +2242,7 @@ SET search_path TO myschema; - See also for other ways to manipulate + See also for other ways to manipulate the schema search path. @@ -2297,7 +2297,7 @@ REVOKE CREATE ON SCHEMA public FROM PUBLIC; public means every user. In the first sense it is an identifier, in the second sense it is a key word, hence the different capitalization; recall the - guidelines from .) + guidelines from .) @@ -2483,7 +2483,7 @@ SELECT name, altitude Given the sample data from the PostgreSQL - tutorial (see ), this returns: + tutorial (see ), this returns: name | altitude @@ -2602,7 +2602,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); capitals table, but this does not happen: INSERT always inserts into exactly the table specified. In some cases it is possible to redirect the insertion - using a rule (see ). However that does not + using a rule (see ). However that does not help for the above case because the cities table does not contain the column state, and so the command will be rejected before the rule can be applied. @@ -2633,11 +2633,11 @@ VALUES ('Albany', NULL, NULL, 'NY'); Table inheritance is typically established when the child table is created, using the INHERITS clause of the - + statement. Alternatively, a table which is already defined in a compatible way can have a new parent relationship added, using the INHERIT - variant of . + variant of . 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 check constraints with the same names and check expressions as those of the @@ -2645,7 +2645,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); NO INHERIT variant of ALTER TABLE. Dynamically adding and removing inheritance links like this can be useful when the inheritance relationship is being used for table - partitioning (see ). + partitioning (see ). @@ -2665,11 +2665,11 @@ VALUES ('Albany', NULL, NULL, 'NY'); if they are inherited 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 - CASCADE option (see ). + CASCADE option (see ). - will + will propagate any changes in column data definitions and check constraints down the inheritance hierarchy. Again, dropping 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 the capitals table could not be updated directly without an additional grant. In a similar way, the parent table's row - security policies (see ) are applied to + security policies (see ) are applied to rows coming from child tables during an inherited query. A child table's policies, if any, are applied only when it is the table explicitly named in the query; and in that case, any policies attached to its parent(s) are @@ -2695,7 +2695,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); - Foreign tables (see ) can also + Foreign tables (see ) can also be part of inheritance hierarchies, either as parent or child tables, just as regular tables can be. If a foreign table is part 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 support recursing over inheritance hierarchies. The respective behavior of each individual command is documented in its reference - page (). + page (). @@ -2923,7 +2923,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); called sub-partitioning. Partitions may have their own indexes, constraints and default values, distinct from those of other partitions. Indexes must be created separately for each partition. See - for more details on creating partitioned + for more details on creating partitioned tables and partitions. @@ -2932,7 +2932,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); vice versa. However, it is possible to add a regular or partitioned table containing data as a partition of a partitioned table, or remove a partition from a partitioned table turning it into a standalone table; - see to learn more about the + see to learn more about the ATTACH PARTITION and DETACH PARTITION sub-commands. @@ -2948,7 +2948,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); inheritance with regular tables. Since a partition hierarchy consisting of the partitioned table and its partitions is still an inheritance hierarchy, all the normal rules of inheritance apply as described in - with some exceptions, most notably: + with some exceptions, most notably: @@ -2999,7 +2999,7 @@ VALUES ('Albany', NULL, NULL, 'NY'); Partitions can also be foreign tables - (see ), + (see ), although these have some limitations that normal tables do not. For example, data inserted into the partitioned table is not routed to foreign table partitions. @@ -3158,7 +3158,7 @@ CREATE INDEX ON measurement_y2008m01 (logdate); - Ensure that the + Ensure that the configuration parameter is not disabled in postgresql.conf. If it is, queries will not be optimized as desired. @@ -3595,7 +3595,7 @@ DO INSTEAD - Ensure that the + Ensure that the configuration parameter is not disabled in postgresql.conf. If it is, queries will not be optimized as desired. @@ -3806,7 +3806,7 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01'; The default (and recommended) setting of - is actually neither + is actually neither on nor off, but an intermediate setting called partition, which causes the technique to be applied only to queries that are likely to be working on partitioned @@ -3889,10 +3889,10 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01'; library that can communicate with an external data source, hiding the details of connecting to the data source and obtaining data from it. There are some foreign data wrappers available as contrib - modules; see . Other kinds of foreign data + modules; see . Other kinds of foreign data 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 . + linkend="fdwhandler"/>. @@ -3918,11 +3918,11 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01'; For additional information, see - , - , - , - , and - . + , + , + , + , and + . @@ -3966,7 +3966,7 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01'; Detailed information on - these topics appears in . + these topics appears in . @@ -3996,7 +3996,7 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01'; PostgreSQL makes sure that you cannot drop objects that other objects still depend on. For example, attempting to drop the products table we considered in , 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: DROP TABLE products; @@ -4066,7 +4066,7 @@ CREATE FUNCTION get_color_note (rainbow) RETURNS text AS LANGUAGE SQL; - (See for an explanation of SQL-language + (See for an explanation of SQL-language functions.) PostgreSQL will be aware that the get_color_note function depends on the rainbow type: dropping the type would force dropping the function, because its diff --git a/doc/src/sgml/dfunc.sgml b/doc/src/sgml/dfunc.sgml index 7ef996b51f..dfefa9e686 100644 --- a/doc/src/sgml/dfunc.sgml +++ b/doc/src/sgml/dfunc.sgml @@ -226,7 +226,7 @@ gcc -G -o foo.so foo.o - Refer back to about where the + Refer back to about where the server expects to find the shared library files. diff --git a/doc/src/sgml/dict-int.sgml b/doc/src/sgml/dict-int.sgml index 04cf14a73d..c15cbd0e4d 100644 --- a/doc/src/sgml/dict-int.sgml +++ b/doc/src/sgml/dict-int.sgml @@ -71,7 +71,7 @@ mydb# select ts_lexize('intdict', '12345678'); but real-world usage will involve including it in a text search - configuration as described in . + configuration as described in . That might look like this: diff --git a/doc/src/sgml/dict-xsyn.sgml b/doc/src/sgml/dict-xsyn.sgml index bf4965c36f..256aff7c58 100644 --- a/doc/src/sgml/dict-xsyn.sgml +++ b/doc/src/sgml/dict-xsyn.sgml @@ -135,7 +135,7 @@ mydb=# SELECT ts_lexize('xsyn', 'syn1'); Real-world usage will involve including it in a text search - configuration as described in . + configuration as described in . That might look like this: diff --git a/doc/src/sgml/diskusage.sgml b/doc/src/sgml/diskusage.sgml index ba23084354..3708e5f3d8 100644 --- a/doc/src/sgml/diskusage.sgml +++ b/doc/src/sgml/diskusage.sgml @@ -20,18 +20,18 @@ stored. If the table has any columns with potentially-wide values, there also might be a TOAST file associated with the table, which is used to store values too wide to fit comfortably in the main - table (see ). There will be one valid index + table (see ). There will be one valid index on the TOAST table, if present. There also might be indexes associated with the base table. Each table and index is stored in a separate disk file — possibly more than one file, if the file would exceed one gigabyte. Naming conventions for these files are described - in . + in . You can monitor disk space in three ways: - using the SQL functions listed in , - using the module, or + using the SQL functions listed in , + using the module, or using manual inspection of the system catalogs. 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 @@ -124,7 +124,7 @@ ORDER BY relpages DESC; 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 systems by making use of tablespaces. See for more information about that. + linkend="manage-ag-tablespaces"/> for more information about that. diff --git a/doc/src/sgml/dml.sgml b/doc/src/sgml/dml.sgml index bc016d3cae..1e05c84fd1 100644 --- a/doc/src/sgml/dml.sgml +++ b/doc/src/sgml/dml.sgml @@ -33,10 +33,10 @@ - To create a new row, use the + To create a new row, use the command. The command requires the table name and column values. For - example, consider the products table from : + example, consider the products table from : CREATE TABLE products ( product_no integer, @@ -107,16 +107,16 @@ INSERT INTO products (product_no, name, price) WHERE release_date = 'today'; This provides the full power of the SQL query mechanism () for computing the rows to be inserted. + linkend="queries"/>) for computing the rows to be inserted. When inserting a lot of data at the same time, considering using - the command. - It is not as flexible as the + the command. + It is not as flexible as the command, but is more efficient. Refer - to for more information on improving + to for more information on improving bulk loading performance. @@ -141,7 +141,7 @@ INSERT INTO products (product_no, name, price) - To update existing rows, use the + To update existing rows, use the command. This requires three pieces of information: @@ -160,7 +160,7 @@ INSERT INTO products (product_no, name, price) - Recall from that SQL does not, in general, + Recall from that SQL does not, in general, provide a unique identifier for rows. Therefore it is not always possible to directly specify which row to update. 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 WHERE condition does not have to be an equality test. Many other operators are - available (see ). But the expression + available (see ). But the expression needs to evaluate to a Boolean result. @@ -243,7 +243,7 @@ UPDATE mytable SET a = 5, b = 3, c = 1 WHERE a > 0; - You use the + You use the command to remove rows; the syntax is very similar to the UPDATE command. For instance, to remove all rows from the products table that have a price of 10, use: @@ -296,7 +296,7 @@ DELETE FROM products; The allowed contents of a RETURNING clause are the same as a SELECT command's output list - (see ). It can contain column + (see ). It can contain column names of the command's target table, or value expressions using those columns. A common shorthand is RETURNING *, which selects all columns of the target table in order. @@ -340,7 +340,7 @@ DELETE FROM products - If there are triggers () on the target table, + If there are triggers () on the target table, the data available to RETURNING is the row as modified by the triggers. Thus, inspecting columns computed by triggers is another common use-case for RETURNING. diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 3a5b88ca1c..090ca95835 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -47,23 +47,11 @@ The documentation sources are written in DocBook, which is a markup language - superficially similar to HTML. Both of these - languages are applications of the Standard Generalized - Markup Language, SGML, which is - essentially a language for describing other languages. In what - follows, the terms DocBook and SGML are both + defined in XML. In what + follows, the terms DocBook and XML are both used, but technically they are not interchangeable. - - - 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. - - - DocBook allows an author to specify the structure and content of a technical document without worrying @@ -97,19 +85,8 @@ This is the definition of DocBook itself. We currently use version 4.2; you cannot use later or earlier versions. You need - the SGML and the XML variant of - the DocBook DTD of the same version. These will usually be in separate - packages. - - - - - - ISO 8879 character entities - - - These are required by DocBook SGML but are distributed separately - because they are maintained by ISO. + the XML variant of the DocBook DTD, not + the SGML variant. @@ -130,17 +107,6 @@ - - OpenSP - - - This is the base package of SGML processing. Note - that we no longer need OpenJade, the DSSSL - processor, only the OpenSP package for converting SGML to XML. - - - - Libxml2 for xmllint @@ -201,7 +167,7 @@ To install the required packages, use: -yum install docbook-dtds docbook-style-xsl fop libxslt opensp +yum install docbook-dtds docbook-style-xsl fop libxslt @@ -209,41 +175,10 @@ yum install docbook-dtds docbook-style-xsl fop libxslt opensp Installation on FreeBSD - - The FreeBSD Documentation Project is itself a heavy user of - DocBook, so it comes as no surprise that there is a full set of - ports of the documentation tools available on - FreeBSD. The following ports need to be installed to build the - documentation on FreeBSD. - - - textproc/docbook-sgml - - - textproc/docbook-xml - - - textproc/docbook-xsl - - - textproc/dsssl-docbook-modular - - - textproc/libxslt - - - textproc/fop - - - textproc/opensp - - - - To install the required packages with pkg, use: -pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp +pkg install docbook-xml docbook-xsl fop libxslt @@ -268,7 +203,7 @@ pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp available for Debian GNU/Linux. To install, simply use: -apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc +apt-get install docbook-xml docbook-xsl fop libxml2-utils xsltproc @@ -277,117 +212,21 @@ apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltpro macOS - If you use MacPorts, the following will get you set up: - -sudo port install docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl fop libxslt opensp - + 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. - - - - Manual Installation from Source - 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 fancy features. For - details, you should study the documentation of the respective - package, and read SGML introductory material. - - - - Installing OpenSP - - - The installation of OpenSP offers a GNU-style - ./configure; make; make install build process. - Details can be found in the OpenSP source distribution. In a nutshell: - -./configure --enable-default-catalog=/usr/local/etc/sgml/catalog -make -make install - - Be sure to remember where you put the default catalog; you - will need it below. You can also leave it off, but then you will have to - set the environment variable SGML_CATALOG_FILES 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.) - - - - - Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit - - - - - Obtain the - DocBook V4.2 distribution. - - - - - - Create the directory - /usr/local/share/sgml/docbook-4.2 and change - to it. (The exact location is irrelevant, but this one is - reasonable within the layout we are following here.) - -$ mkdir /usr/local/share/sgml/docbook-4.2 -$ cd /usr/local/share/sgml/docbook-4.2 - - - - - - - Unpack the archive: - -$ unzip -a ...../docbook-4.2.zip - - (The archive will unpack its files into the current directory.) - - - - - - Edit the file - /usr/local/share/sgml/catalog (or whatever - you told jade during installation) and put a line like this - into it: + If you use MacPorts, the following will get you set up: -CATALOG "docbook-4.2/docbook.cat" +sudo port install docbook-xml-4.2 docbook-xsl fop - - - - - - Download the - ISO 8879 character entities archive, unpack it, and put the - files in the same directory you put the DocBook files in: - -$ cd /usr/local/share/sgml/docbook-4.2 -$ unzip ...../ISOEnts.zip - - - - - - - Run the following command in the directory with the DocBook and ISO files: + If you use Homebrew, use this: -perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat +brew install docbook docbook-xsl fop - (This fixes a mixup between the names used in the DocBook - catalog file and the actual names of the ISO character entity - files.) - - - - + @@ -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 like this: - -checking for onsgmls... onsgmls -checking for DocBook V4.2... yes -checking for dbtoepub... dbtoepub checking for xmllint... xmllint +checking for DocBook XML V4.2... yes +checking for dbtoepub... dbtoepub checking for xsltproc... xsltproc -checking for osx... osx checking for fop... fop - - If neither onsgmls nor - nsgmls were found then some of the following tests - will be skipped. nsgmls is part of the OpenSP - package. You can pass the environment variable - NSGMLS to configure to point - to the programs if they are not found automatically. If - DocBook V4.2 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. + If xmllint was not found then some of the following + tests will be skipped. @@ -464,9 +291,7 @@ checking for fop... fop We use the DocBook XSL stylesheets to convert DocBook refentry pages to *roff output suitable for man - pages. The man pages are also distributed as a tar archive, - similar to the HTML version. To create the man - pages, use the commands: + pages. To create the man pages, use the command: doc/src/sgml$ make man @@ -536,7 +361,7 @@ ADDITIONAL_FLAGS='-Xmx1000m' The installation instructions are also distributed as plain text, in case they are needed in a situation where better reading tools are not available. The INSTALL file - corresponds to , with some minor + corresponds to , with some minor changes to account for the different context. To recreate the file, change to the directory doc/src/sgml and enter make INSTALL. diff --git a/doc/src/sgml/earthdistance.sgml b/doc/src/sgml/earthdistance.sgml index 1bdcf64629..1f3ea6aa6e 100644 --- a/doc/src/sgml/earthdistance.sgml +++ b/doc/src/sgml/earthdistance.sgml @@ -56,7 +56,7 @@ The provided functions are shown - in . + in . @@ -150,7 +150,7 @@ A single operator is provided, shown - in . + in .
diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml index bc3d080774..d1872c1a5c 100644 --- a/doc/src/sgml/ecpg.sgml +++ b/doc/src/sgml/ecpg.sgml @@ -31,7 +31,7 @@ specially marked sections. To build the program, the source code (*.pgc) is first passed through the embedded SQL preprocessor, which converts it to an ordinary C program (*.c), and afterwards it can be processed by a C - compiler. (For details about the compiling and linking see ). + compiler. (For details about the compiling and linking see ). Converted ECPG applications call functions in the libpq library through the embedded SQL library (ecpglib), and communicate with the PostgreSQL server using the normal frontend-backend protocol. @@ -397,9 +397,9 @@ EXEC SQL COMMIT; row can also be executed using EXEC SQL directly. To handle result sets with multiple rows, an application has to use a cursor; - see below. (As a special case, an + see below. (As a special case, an application can fetch multiple rows at once into an array host - variable; see .) + variable; see .) @@ -422,7 +422,7 @@ EXEC SQL SHOW search_path INTO :var; :something are host variables, that is, they refer to variables in the C program. They are explained in . + linkend="ecpg-variables"/>. @@ -452,8 +452,8 @@ EXEC SQL COMMIT; For more details about declaration of the cursor, - see , and - see for FETCH command + see , and + see for FETCH command details. @@ -477,7 +477,7 @@ EXEC SQL COMMIT; interface also supports autocommit of transactions (similar to psql's default behavior) via the command-line option to ecpg (see ) or via the EXEC SQL SET AUTOCOMMIT TO + linkend="app-ecpg"/>) or via the EXEC SQL SET AUTOCOMMIT TO ON statement. In autocommit mode, each command is automatically committed unless it is inside an explicit transaction block. This mode can be explicitly turned off using EXEC @@ -617,8 +617,8 @@ EXEC SQL DEALLOCATE PREPARE name; For more details about PREPARE, - see . Also - see for more details about using + see . Also + see for more details about using placeholders and input parameters. @@ -628,7 +628,7 @@ EXEC SQL DEALLOCATE PREPARE name; Using Host Variables - In you saw how you can execute SQL + In you saw how you can execute SQL statements from an embedded SQL program. Some of those statements only used fixed values and did not provide a way to insert user-supplied values into statements or have the program process @@ -646,7 +646,7 @@ EXEC SQL DEALLOCATE PREPARE name; Another way to exchange values between PostgreSQL backends and ECPG applications is the use of SQL descriptors, described - in . + in . @@ -812,11 +812,11 @@ do directly. Other PostgreSQL data types, such as timestamp and numeric can only be accessed through special library functions; see - . + . - shows which PostgreSQL + shows which PostgreSQL data types correspond to which C data types. When you wish to send or receive a value of a given PostgreSQL data type, you should declare a C variable of the corresponding C data type in @@ -851,12 +851,12 @@ do decimal - decimalThis type can only be accessed through special library functions; see . + decimalThis type can only be accessed through special library functions; see . numeric - numeric + numeric @@ -901,17 +901,17 @@ do timestamp - timestamp + timestamp interval - interval + interval date - date + date @@ -1002,7 +1002,7 @@ struct varchar_var { int len; char arr[180]; } var; structure. Applications deal with these types by declaring host variables in special types and accessing them using functions in the pgtypes library. The pgtypes library, described in detail - in contains basic functions to deal + in contains basic functions to deal 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 example. @@ -1011,7 +1011,7 @@ struct varchar_var { int len; char arr[180]; } var; The follow subsections describe these special data types. For more details about pgtypes library functions, - see . + see . @@ -1062,7 +1062,7 @@ ts = 2010-06-27 18:03:56.949343 program has to include pgtypes_date.h, declare a host variable as the date type and convert a DATE value into a text form using PGTYPESdate_to_asc() function. For more details about the - pgtypes library functions, see . + pgtypes library functions, see . @@ -1117,7 +1117,7 @@ EXEC SQL END DECLARE SECTION; allocating some memory space on the heap, and accessing the variable using the pgtypes library functions. For more details about the pgtypes library functions, - see . + see . @@ -1193,7 +1193,7 @@ EXEC SQL END DECLARE SECTION; There are two use cases for arrays as host variables. The first is a way to store some text string in char[] or VARCHAR[], as - explained in . The second use case is to + explained in . The second use case is to retrieve multiple rows from a query result without using a cursor. Without an array, to process a query result consisting of multiple rows, it is required to use a cursor and @@ -1378,7 +1378,7 @@ EXEC SQL TYPE serial_t IS long; You can declare pointers to the most common types. Note however that you cannot use pointers as target variables of queries - without auto-allocation. See + without auto-allocation. See for more information on auto-allocation. @@ -1520,7 +1520,7 @@ while (1) Another workaround is to store arrays in their external string representation in host variables of type char[] or VARCHAR[]. For more details about this - representation, see . Note that + representation, see . Note that this means that the array cannot be accessed naturally as an array in the host program (without further processing that parses the text representation). @@ -1578,7 +1578,7 @@ EXEC SQL CLOSE cur1; To enhance this example, the host variables to store values in the FETCH command can be gathered into one structure. For more details about the host variable in the - structure form, see . + structure form, see . To switch to the structure, the example can be modified as below. The two host variables, intval and textval, become members of @@ -1659,12 +1659,12 @@ while (1) Here is an example using the data type complex from - the example in . The external string + the example in . The external string representation of that type is (%lf,%lf), which is defined in the functions complex_in() and complex_out() functions - in . The following example inserts the + in . The following example inserts the complex type values (1,1) and (3,3) into the columns a and b, and select @@ -1875,7 +1875,7 @@ EXEC SQL EXECUTE mystmt INTO :v1, :v2, :v3 USING 37; If a query is expected to return more than one result row, a cursor should be used, as in the following example. - (See for more details about the + (See for more details about the cursor.) EXEC SQL BEGIN DECLARE SECTION; @@ -1941,7 +1941,7 @@ free(out); The numeric Type The numeric type offers to do calculations with arbitrary precision. See - for the equivalent type in the + for the equivalent type in the PostgreSQL server. Because of the arbitrary precision this 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 @@ -2264,7 +2264,7 @@ int PGTYPESnumeric_from_decimal(decimal *src, numeric *dst); The date Type The date type in C enables your programs to deal with data of the SQL type - date. See for the equivalent type in the + date. See for the equivalent type in the PostgreSQL server. @@ -2303,7 +2303,7 @@ date PGTYPESdate_from_asc(char *str, char **endptr); currently no variable to change that within ECPG. - shows the allowed input formats. + shows the allowed input formats.
Valid Input Formats for <function>PGTYPESdate_from_asc</function> @@ -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. - indicates a few possible formats. This will give + indicates a few possible formats. This will give you an idea of how to use this function. All output lines are based on the same date: November 23, 1959. @@ -2649,7 +2649,7 @@ int PGTYPESdate_defmt_asc(date *d, char *fmt, char *str); day. - indicates a few possible formats. This will give + indicates a few possible formats. This will give you an idea of how to use this function.
@@ -2741,7 +2741,7 @@ int PGTYPESdate_defmt_asc(date *d, char *fmt, char *str); The timestamp Type The timestamp type in C enables your programs to deal with data of the SQL - type timestamp. See for the equivalent + type timestamp. See for the equivalent type in the PostgreSQL server. @@ -2766,7 +2766,7 @@ timestamp PGTYPEStimestamp_from_asc(char *str, char **endptr); The function returns the parsed timestamp on success. On error, PGTYPESInvalidTimestamp is returned and errno is - set to PGTYPES_TS_BAD_TIMESTAMP. See for important notes on this value. + set to PGTYPES_TS_BAD_TIMESTAMP. See for important notes on this value. 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. - contains a few examples for input strings. + contains a few examples for input strings.
Valid Input Formats for <function>PGTYPEStimestamp_from_asc</function> @@ -3217,7 +3217,7 @@ int PGTYPEStimestamp_defmt_asc(char *str, char *fmt, timestamp *d); This is the reverse function to . See the documentation there in + linkend="pgtypestimestampfmtasc"/>. See the documentation there in order to find out about the possible formatting mask entries. @@ -3270,7 +3270,7 @@ int PGTYPEStimestamp_sub_interval(timestamp *tin, interval *span, timestamp *tou The interval Type The interval type in C enables your programs to deal with data of the SQL - type interval. See for the equivalent + type interval. See for the equivalent type in the PostgreSQL server. @@ -3364,7 +3364,7 @@ int PGTYPESinterval_copy(interval *intvlsrc, interval *intvldest); PGTYPESdecimal_free). There are a lot of other functions that deal with the decimal type in the Informix compatibility mode described in . + linkend="ecpg-informix-compat"/>. 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 DESCRIPTOR and SQL DESCRIPTOR produced named SQL Descriptor Areas. Now it is mandatory, omitting the SQL keyword produces SQLDA Descriptor Areas, - see . + see . @@ -3853,7 +3853,7 @@ EXEC SQL FETCH 3 FROM mycursor INTO DESCRIPTOR mysqlda; Note that the SQL keyword is omitted. The paragraphs about the use cases of the INTO and USING - keywords in also apply here with an addition. + keywords in also apply here with an addition. In a DESCRIBE statement the DESCRIPTOR keyword can be completely omitted if the INTO keyword is used: @@ -4038,7 +4038,7 @@ typedef struct sqlvar_struct sqlvar_t; Points to the data. The format of the data is described - in . + in . @@ -4447,7 +4447,7 @@ main(void) The whole program is shown - in . + in . @@ -5016,7 +5016,7 @@ sqlstate: 42P01 SQLSTATE error codes; therefore a high degree of consistency can be achieved by using this error code scheme throughout all applications. For further information see - . + . @@ -5037,7 +5037,7 @@ sqlstate: 42P01 SQLSTATE is also listed. There is, however, no one-to-one or one-to-many mapping between the two schemes (indeed it is many-to-many), so you should consult the global - SQLSTATE listing in + SQLSTATE listing in in each case. @@ -5767,7 +5767,7 @@ ECPG = ecpg The complete syntax of the ecpg command is - detailed in . + detailed in . @@ -5835,7 +5835,7 @@ ECPG = ecpg ECPGtransactionStatus(const char *connection_name) returns the current transaction status of the given connection identified by connection_name. - See and libpq's PQtransactionStatus() for details about the returned status codes. + See and libpq's PQtransactionStatus() for details about the returned status codes. @@ -5867,8 +5867,8 @@ ECPG = ecpg For more details about the ECPGget_PGconn(), see - . For information about the large - object function interface, see . + . For information about the large + object function interface, see . @@ -5878,7 +5878,7 @@ ECPG = ecpg - shows an example program that + shows an example program that illustrates how to create, write, and read a large object in an ECPG application. @@ -5997,7 +5997,7 @@ main(void) 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 calls into to access the database, and linking that together with - the rest of the C++ code. See + the rest of the C++ code. See about that. @@ -6252,7 +6252,7 @@ c++ test_cpp.o test_mod.o -lecpg -o test_cpp This section describes all SQL commands that are specific to embedded SQL. Also refer to the SQL commands listed - in , which can also be used in + in , which can also be used in embedded SQL, unless stated otherwise. @@ -6320,9 +6320,9 @@ EXEC SQL ALLOCATE DESCRIPTOR mydesc; See Also - - - + + + @@ -6539,8 +6539,8 @@ EXEC SQL END DECLARE SECTION; See Also - - + + @@ -6604,9 +6604,9 @@ EXEC SQL DEALLOCATE DESCRIPTOR mydesc; See Also - - - + + + @@ -6668,8 +6668,8 @@ DECLARE cursor_name [ BINARY ] [ IN query - A or - command which will provide the + A or + command which will provide the rows to be returned by the cursor. @@ -6678,7 +6678,7 @@ DECLARE cursor_name [ BINARY ] [ IN For the meaning of the cursor options, - see . + see . @@ -6715,9 +6715,9 @@ EXEC SQL DECLARE cur1 CURSOR FOR stmt1; See Also - - - + + + @@ -6805,8 +6805,8 @@ EXEC SQL DEALLOCATE DESCRIPTOR mydesc; See Also - - + + @@ -6915,8 +6915,8 @@ main(void) See Also - - + + @@ -7056,7 +7056,7 @@ GET DESCRIPTOR descriptor_name VALU A token identifying which item of information about a column - to retrieve. See for + to retrieve. See for a list of supported items. @@ -7164,8 +7164,8 @@ d_data = testdb See Also - - + + @@ -7258,8 +7258,8 @@ EXEC SQL OPEN :curname1; See Also - - + + @@ -7282,8 +7282,8 @@ PREPARE name FROM PREPARE prepares a statement dynamically specified as a string for execution. This is different from the - direct SQL statement , which can also - be used in embedded programs. The + direct SQL statement , which can also + be used in embedded programs. The command is used to execute either kind of prepared statement. @@ -7338,7 +7338,7 @@ EXEC SQL EXECUTE foo USING SQL DESCRIPTOR indesc INTO SQL DESCRIPTOR outdesc; See Also - + @@ -7445,8 +7445,8 @@ EXEC SQL SET CONNECTION = con1; See Also - - + + @@ -7520,7 +7520,7 @@ SET DESCRIPTOR descriptor_name VALU A token identifying which item of information to set in the - descriptor. See for a + descriptor. See for a list of supported items. @@ -7561,8 +7561,8 @@ EXEC SQL SET DESCRIPTOR indesc VALUE 2 INDICATOR = :val2null, DATA = :val2; See Also - - + + @@ -7796,7 +7796,7 @@ WHENEVER { NOT FOUND | SQLERROR | SQLWARNING } ac Parameters - See for a description of the + See for a description of the parameters. @@ -7979,7 +7979,7 @@ EXEC SQL CLOSE DATABASE; Informix-compatible SQLDA Descriptor Areas Informix-compatible mode supports a different structure than the one described in - . See below: + . See below: struct sqlvar_compat { @@ -8653,7 +8653,7 @@ void rtoday(date *d); that it sets to the current date. - Internally this function uses the + Internally this function uses the function. @@ -8678,7 +8678,7 @@ int rjulmdy(date d, short mdy[3]); The function always returns 0 at the moment. - Internally the function uses the + Internally the function uses the function. @@ -8748,7 +8748,7 @@ int rdefmtdate(date *d, char *fmt, char *str); Internally this function is implemented to use the function. See the reference there for a + linkend="pgtypesdatedefmtasc"/> function. See the reference there for a table of example input. @@ -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. - Internally this function uses the + Internally this function uses the function, see the reference there for examples. @@ -8795,7 +8795,7 @@ int rmdyjul(short mdy[3], date *d); Internally the function is implemented to use the function . + linkend="pgtypesdatemdyjul"/>. @@ -8851,7 +8851,7 @@ int rdayofweek(date d); Internally the function is implemented to use the function . + linkend="pgtypesdatedayofweek"/>. @@ -8889,7 +8889,7 @@ int dtcvasc(char *str, timestamp *ts); Internally this function uses the function. See the reference there + linkend="pgtypestimestampfromasc"/> function. See the reference there for a table with example inputs. @@ -8911,7 +8911,7 @@ dtcvfmtasc(char *inbuf, char *fmtstr, timestamp *dtvalue) This function is implemented by means of the function. See the documentation + linkend="pgtypestimestampdefmtasc"/> function. See the documentation there for a list of format specifiers that can be used. @@ -8983,7 +8983,7 @@ int dttofmtasc(timestamp *ts, char *output, int str_len, char *fmtstr); Internally, this function uses the function. See the reference there for + linkend="pgtypestimestampfmtasc"/> function. See the reference there for information on what format mask specifiers can be used. @@ -9289,7 +9289,7 @@ int risnull(int t, char *ptr); The function receives the type of the variable to test (t) as well a pointer to this variable (ptr). Note that the latter needs to be cast to a char*. See the function for a list of possible variable types. + linkend="rsetnull"/> for a list of possible variable types. Here is an example of how to use this function: diff --git a/doc/src/sgml/errcodes.sgml b/doc/src/sgml/errcodes.sgml index 61ad3e00e9..6fd16f643e 100644 --- a/doc/src/sgml/errcodes.sgml +++ b/doc/src/sgml/errcodes.sgml @@ -32,7 +32,7 @@ - lists all the error codes defined in + lists all the error codes defined in PostgreSQL &version;. (Some are not actually used at present, but are defined by the SQL standard.) The error classes are also shown. For each error class there is a @@ -66,9 +66,9 @@ <productname>PostgreSQL</productname> Error Codes - - - + + + diff --git a/doc/src/sgml/event-trigger.sgml b/doc/src/sgml/event-trigger.sgml index c16ff338a3..0a8860490a 100644 --- a/doc/src/sgml/event-trigger.sgml +++ b/doc/src/sgml/event-trigger.sgml @@ -8,7 +8,7 @@ - To supplement the trigger mechanism discussed in , + To supplement the trigger mechanism discussed in , PostgreSQL also provides event triggers. Unlike regular 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 @@ -57,7 +57,7 @@ operations that took place, use the set-returning function pg_event_trigger_ddl_commands() from the ddl_command_end event trigger code (see - ). Note that the trigger fires + ). Note that the trigger fires after the actions have taken place (but before the transaction commits), and thus the system catalogs can be read as already changed. @@ -68,7 +68,7 @@ database objects. To list the objects that have been dropped, use the set-returning function pg_event_trigger_dropped_objects() from the sql_drop event trigger code (see - ). Note that + ). Note that the trigger is executed after the objects have been deleted from the system catalogs, so it's not possible to look them up anymore. @@ -96,11 +96,11 @@ For a complete list of commands supported by the event trigger mechanism, - see . + see . - Event triggers are created using the command . + Event triggers are created using the command . In order to create an event trigger, you must first create a function with the special return type event_trigger. This function need not (and may not) return a value; the return type serves merely as @@ -125,7 +125,7 @@ Event Trigger Firing Matrix - lists all commands + lists all commands for which event triggers are supported. @@ -953,7 +953,7 @@ typedef struct EventTriggerData Describes the event for which the function is called, one of "ddl_command_start", "ddl_command_end", "sql_drop", "table_rewrite". - See for the meaning of these + See for the meaning of these events. @@ -1003,7 +1003,7 @@ typedef struct EventTriggerData The event trigger definition associated the function with the ddl_command_start event. The effect is that all DDL commands (with the exceptions mentioned - in ) are prevented from running. + in ) are prevented from running. @@ -1037,7 +1037,7 @@ noddl(PG_FUNCTION_ARGS) - After you have compiled the source code (see ), + After you have compiled the source code (see ), declare the function and the triggers: CREATE FUNCTION noddl() RETURNS event_trigger diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml index e819010875..5f1bb70e97 100644 --- a/doc/src/sgml/extend.sgml +++ b/doc/src/sgml/extend.sgml @@ -15,32 +15,32 @@ - functions (starting in ) + functions (starting in ) - aggregates (starting in ) + aggregates (starting in ) - data types (starting in ) + data types (starting in ) - operators (starting in ) + operators (starting in ) - operator classes for indexes (starting in ) + operator classes for indexes (starting in ) - packages of related objects (starting in ) + packages of related objects (starting in ) @@ -132,14 +132,14 @@ types through functions provided by the user and only understands the behavior of such types to the extent that the user describes them. - The built-in base types are described in . + The built-in base types are described in . Enumerated (enum) types can be considered as a subcategory of base types. The main difference is that they can be created using just SQL commands, without any low-level programming. - Refer to for more information. + Refer to for more information. @@ -157,25 +157,25 @@ 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 the type system is concerned, multi-dimensional arrays are the same as - one-dimensional arrays. Refer to for more + one-dimensional arrays. Refer to for more information. Composite types, or row types, are created whenever the user creates a table. It is also possible to use to + linkend="sql-createtype"/> to define a stand-alone composite type with no associated table. A composite type is simply a list of types with associated field names. A value of a composite type is a row or - record of field values. Refer to + record of field values. Refer to for more information. 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 - a few built-in ones exist. Refer to + a few built-in ones exist. Refer to for more information. @@ -188,8 +188,8 @@ is interchangeable with its underlying type. However, a domain can have constraints that restrict its valid values to a subset of what the underlying type would allow. Domains are created using - the SQL command . - Refer to for more information. + the SQL command . + Refer to for more information. @@ -202,7 +202,7 @@ container types, but they can be used to declare the argument and result types of functions. This provides a mechanism within the type system to identify special classes of functions. lists the existing + linkend="datatype-pseudotypes-table"/> lists the existing pseudo-types. @@ -300,7 +300,7 @@ A variadic function (one taking a variable number of arguments, as in - ) can be + ) can be polymorphic: this is accomplished by declaring its last parameter as VARIADIC anyarray. For purposes of argument 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 will typically also be a shared library file into which the C code has been built. Once you have these files, a simple - command loads the objects into + command loads the objects into your database. @@ -346,7 +346,7 @@ SQL script to load a bunch of loose objects into your database, is that PostgreSQL will then understand that the objects of the extension go together. You can - drop all the objects with a single + drop all the objects with a single command (no need to maintain a separate uninstall script). Even more useful, pg_dump knows that it should not dump the individual member objects of the extension — it will @@ -366,7 +366,7 @@ by pg_dump. Such a change is usually only sensible if you concurrently make the same change in the extension's script file. (But there are special provisions for tables containing configuration - data; see .) + data; see .) In production situations, it's generally better to create an extension update script to perform changes to extension member objects. @@ -405,7 +405,7 @@ The kinds of SQL objects that can be members of an extension are shown in - the description of . Notably, objects + the description of . Notably, objects that are database-cluster-wide, such as databases, roles, and tablespaces, cannot be extension members since an extension is only known within one database. (Although an extension script is not prohibited from creating @@ -438,7 +438,7 @@ - The command relies on a control + The command relies on a control file for each extension, which must be named the same as the extension with a suffix of .control, and must be placed in the installation's SHAREDIR/extension directory. There @@ -499,7 +499,7 @@ when initially creating an extension, but not during extension updates (since that might override user-added comments). Alternatively, the extension's comment can be set by writing - a command in the script file. + a command in the script file. @@ -562,7 +562,7 @@ its contained objects into a different schema after initial creation of the extension. The default is false, i.e. the extension is not relocatable. - See for more information. + See for more information. @@ -576,7 +576,7 @@ and not any other. The schema parameter is consulted only when initially creating an extension, not during extension updates. - See for more information. + See for more information. @@ -609,7 +609,7 @@ comments) by the extension mechanism. This provision is commonly used to throw an error if the script file is fed to psql rather than being loaded via CREATE EXTENSION (see example - script in ). + script in ). Without that, users might accidentally load the extension's contents as loose objects rather than as an extension, a state of affairs that's a bit tedious to recover from. @@ -687,7 +687,7 @@ In all cases, the script file will be executed with - initially set to point to the target + initially set to point to the target schema; that is, CREATE EXTENSION does the equivalent of this: @@ -1031,14 +1031,14 @@ include $(PGXS) This makefile relies on PGXS, which is described - in . The command make install + in . The command make install will install the control and script files into the correct directory as reported by pg_config. Once the files are installed, use the - command to load the objects into + command to load the objects into any particular database. diff --git a/doc/src/sgml/external-projects.sgml b/doc/src/sgml/external-projects.sgml index 03fd18aeb8..89147817ec 100644 --- a/doc/src/sgml/external-projects.sgml +++ b/doc/src/sgml/external-projects.sgml @@ -40,7 +40,7 @@ All other language interfaces are external projects and are distributed - separately. includes a list of + separately. includes a list of some of these projects. Note that some of these packages might not be released under the same license as PostgreSQL. For more information on each language interface, including licensing terms, refer to @@ -170,7 +170,7 @@ In addition, there are a number of procedural languages that are developed and maintained outside the core PostgreSQL - distribution. lists some of these + distribution. lists some of these packages. Note that some of these projects might not be released under the same license as PostgreSQL. For more information on each procedural language, including licensing information, refer to its website @@ -238,7 +238,7 @@ just like features that are built in. The contrib/ directory shipped with the source code contains several extensions, which are described in - . Other extensions are developed + . Other extensions are developed independently, like PostGIS. Even PostgreSQL replication solutions can be developed diff --git a/doc/src/sgml/fdwhandler.sgml b/doc/src/sgml/fdwhandler.sgml index 4250a03f16..a2f8137713 100644 --- a/doc/src/sgml/fdwhandler.sgml +++ b/doc/src/sgml/fdwhandler.sgml @@ -22,7 +22,7 @@ The foreign data wrappers included in the standard distribution are good references when trying to write your own. Look into the contrib subdirectory of the source tree. - The reference page also has + The reference page also has some useful details. @@ -43,7 +43,7 @@ a validator function. Both functions must be written in a compiled language such as C, using the version-1 interface. For details on C language calling conventions and dynamic loading, - see . + see . @@ -57,7 +57,7 @@ returning the special pseudo-type fdw_handler. The callback functions are plain C functions and are not visible or callable at the SQL level. The callback functions are described in - . + . @@ -126,7 +126,7 @@ GetForeignRelSize(PlannerInfo *root, - See for additional information. + See for additional information. @@ -157,7 +157,7 @@ GetForeignPaths(PlannerInfo *root, - See for additional information. + See for additional information. @@ -193,7 +193,7 @@ GetForeignPlan(PlannerInfo *root, - See for additional information. + See for additional information. @@ -341,7 +341,7 @@ GetForeignJoinPaths(PlannerInfo *root, - See for additional information. + See for additional information. @@ -388,7 +388,7 @@ GetForeignUpperPaths(PlannerInfo *root, - See for additional information. + See for additional information. @@ -477,7 +477,7 @@ PlanForeignModify(PlannerInfo *root, - See for additional information. + See for additional information. @@ -759,7 +759,7 @@ PlanDirectModify(PlannerInfo *root, - See for additional information. + See for additional information. @@ -872,7 +872,7 @@ EndDirectModify(ForeignScanState *node); If an FDW wishes to support late row locking (as described - in ), it must provide the following + in ), it must provide the following callback functions: @@ -905,7 +905,7 @@ GetForeignRowMarkType(RangeTblEntry *rte, - See for more information. + See for more information. @@ -964,7 +964,7 @@ RefetchForeignRow(EState *estate, - See for more information. + See for more information. @@ -1093,7 +1093,7 @@ AnalyzeForeignTable(Relation relation, BlockNumber *totalpages); - This function is called when is executed on + This function is called when is executed on a foreign table. If the FDW can collect statistics for this foreign table, it should return true, and provide a pointer to a function that will collect sample rows from the table in @@ -1139,10 +1139,10 @@ ImportForeignSchema(ImportForeignSchemaStmt *stmt, Oid serverOid); Obtain a list of foreign table creation commands. This function is - called when executing , and is + called when executing , and is 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 - which must contain a command. + which must contain a command. These strings will be parsed and executed by the core server. @@ -1605,7 +1605,7 @@ GetForeignServerByName(const char *name, bool missing_ok); PlanForeignModify and the other callbacks described in - are designed around the assumption + are designed around the assumption that the foreign relation will be scanned in the usual way and then individual row updates will be driven by a local ModifyTable 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 ModifyTable approach. This approach could also be used to implement remote SELECT FOR UPDATE, rather than using the row locking callbacks described in - . Keep in mind that a path + . Keep in mind that a path inserted into UPPERREL_FINAL is responsible for implementing all behavior of the query. @@ -1676,7 +1676,7 @@ GetForeignServerByName(const char *name, bool missing_ok); By default, PostgreSQL ignores locking considerations when interfacing to FDWs, but an FDW can perform early locking without any explicit support from the core code. The API functions described - in , which were added + in , which were added in PostgreSQL 9.5, allow an FDW to use late locking if it wishes. @@ -1720,7 +1720,7 @@ GetForeignServerByName(const char *name, bool missing_ok); again perform early locking by fetching tuples with the equivalent of SELECT FOR UPDATE/SHARE. To perform late locking instead, provide the callback functions defined - in . + in . In GetForeignRowMarkType, select rowmark option ROW_MARK_EXCLUSIVE, ROW_MARK_NOKEYEXCLUSIVE, ROW_MARK_SHARE, or ROW_MARK_KEYSHARE depending diff --git a/doc/src/sgml/file-fdw.sgml b/doc/src/sgml/file-fdw.sgml index 88aefb8ef0..e2598a07da 100644 --- a/doc/src/sgml/file-fdw.sgml +++ b/doc/src/sgml/file-fdw.sgml @@ -13,7 +13,7 @@ files in the server's file system, or to execute programs on the server and read their output. The data file or program output must be in a format that can be read by COPY FROM; - see for details. + see for details. Access to data files is currently read-only. diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 698daf69ea..4dd9d029e6 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -15,7 +15,7 @@ PostgreSQL provides a large number of functions and operators for the built-in data types. Users can also define their own functions and operators, as described in - . The + . The psql commands \df and \do can be used to list all available functions and operators, respectively. @@ -176,7 +176,7 @@ The operators AND and OR are commutative, that is, you can switch the left and right operand without affecting the result. But see for more information about the + linkend="syntax-express-eval"/> for more information about the order of evaluation of subexpressions. @@ -191,7 +191,7 @@ The usual comparison operators are available, as shown in . + linkend="functions-comparison-op-table"/>.
@@ -258,7 +258,7 @@ There are also some comparison predicates, as shown in . These behave much like + linkend="functions-comparison-pred-table"/>. These behave much like operators, but have special syntax mandated by the SQL standard. @@ -455,7 +455,7 @@ returns true if expression evaluates to the null value. It is highly recommended that these applications be modified to comply with the SQL standard. However, if that - cannot be done the + cannot be done the configuration variable is available. If it is enabled, PostgreSQL will convert x = NULL clauses to x IS NULL. @@ -536,7 +536,7 @@ Some comparison-related functions are also available, as shown in . + linkend="functions-comparison-func-table"/>.
@@ -591,7 +591,7 @@ - shows the available mathematical operators. + shows the available mathematical operators.
@@ -736,11 +736,11 @@ the others are available for all numeric data types. The bitwise operators are also available for the bit string types bit and bit varying, as - shown in . + shown in . - shows the available + shows the available mathematical functions. In the table, dp indicates double precision. Many of these functions are provided in multiple forms with different argument types. @@ -1093,7 +1093,7 @@
- shows functions for + shows functions for generating random numbers. @@ -1139,11 +1139,11 @@ The characteristics of the values returned by random() depend on the system implementation. It is not suitable for cryptographic - applications; see module for an alternative. + applications; see module for an alternative. - Finally, shows the + Finally, shows the available trigonometric functions. All trigonometric functions take arguments and return values of type double precision. Each of the trigonometric functions comes in @@ -1328,10 +1328,10 @@ SQL defines some string functions that use key words, rather than commas, to separate arguments. Details are in - . + . PostgreSQL also provides versions of these functions that use the regular function invocation syntax - (see ). + (see ). @@ -1343,7 +1343,7 @@ caused surprising behaviors. However, the string concatenation operator (||) still accepts non-string input, so long as at least one input is of a string type, as shown in . For other cases, insert an explicit + linkend="functions-string-sql"/>. For other cases, insert an explicit coercion to text if you need to duplicate the previous behavior. @@ -1504,7 +1504,7 @@ text Extract substring matching POSIX regular expression. See - for more information on pattern + for more information on pattern matching. substring('Thomas' from '...$') @@ -1516,7 +1516,7 @@ text Extract substring matching SQL regular expression. - See for more information on + See for more information on pattern matching. substring('Thomas' from '%#"o_a#"_' for '#') @@ -1577,8 +1577,8 @@ Additional string manipulation functions are available and are - listed in . Some of them are used internally to implement the - SQL-standard string functions listed in . + listed in . Some of them are used internally to implement the + SQL-standard string functions listed in . @@ -1702,7 +1702,7 @@ string must be valid in this encoding. Conversions can be defined by CREATE CONVERSION. Also there are some predefined conversions. See for available conversions. + linkend="conversion-names"/> for available conversions. convert('text_in_utf8', 'UTF8', 'LATIN1') text_in_utf8 represented in Latin-1 @@ -1792,7 +1792,7 @@ Format arguments according to a format string. This function is similar to the C function sprintf. - See . + See . format('Hello %s, %1$s', 'World') Hello World, World @@ -1968,7 +1968,7 @@ Quotes are added only if necessary (i.e., if the string contains non-identifier characters or would be case-folded). Embedded quotes are properly doubled. - See also . + See also . quote_ident('Foo bar') "Foo bar" @@ -1989,7 +1989,7 @@ Note that quote_literal returns null on null input; if the argument might be null, quote_nullable is often more suitable. - See also . + See also . quote_literal(E'O\'Reilly') 'O''Reilly' @@ -2019,7 +2019,7 @@ in an SQL statement string; or, if the argument is null, return NULL. Embedded single-quotes and backslashes are properly doubled. - See also . + See also . quote_nullable(NULL) NULL @@ -2048,7 +2048,7 @@ Return captured substring(s) resulting from the first match of a POSIX regular expression to the string. See - for more information. + for more information. regexp_match('foobarbequebaz', '(bar)(beque)') {bar,beque} @@ -2065,7 +2065,7 @@ Return captured substring(s) resulting from matching a POSIX regular expression to the string. See - for more information. + for more information. regexp_matches('foobarbequebaz', 'ba.', 'g') {bar}{baz} (2 rows) @@ -2081,7 +2081,7 @@ text Replace substring(s) matching a POSIX regular expression. See - for more information. + for more information. regexp_replace('Thomas', '.[mN]a.', 'M') ThM @@ -2097,7 +2097,7 @@ text[] Split string using a POSIX regular expression as - the delimiter. See for more + the delimiter. See for more information. regexp_split_to_array('hello world', E'\\s+') @@ -2114,7 +2114,7 @@ setof text Split string using a POSIX regular expression as - the delimiter. See for more + the delimiter. See for more information. regexp_split_to_table('hello world', E'\\s+') @@ -2339,7 +2339,7 @@ format functions are variadic, so it is possible to pass the values to be concatenated or formatted as an array marked with the VARIADIC keyword (see ). The array's elements are + linkend="xfunc-sql-variadic-functions"/>). The array's elements are treated as if they were separate ordinary arguments to the function. If the variadic array argument is NULL, concat and concat_ws return NULL, but @@ -2348,7 +2348,7 @@ See also the aggregate function string_agg in - . + .
@@ -3351,7 +3351,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); The %I and %L format specifiers are particularly useful for safely constructing dynamic SQL statements. See - . + . @@ -3375,10 +3375,10 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); SQL defines some string functions that use key words, rather than commas, to separate arguments. Details are in - . + . PostgreSQL also provides versions of these functions that use the regular function invocation syntax - (see ). + (see ). @@ -3498,10 +3498,10 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); Additional binary string manipulation functions are available and - are listed in . Some + are listed in . Some of them are used internally to implement the SQL-standard string functions listed in . + linkend="functions-binarystring-sql"/>.
@@ -3688,8 +3688,8 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); See also the aggregate function string_agg in - and the large object functions - in . + and the large object functions + in . @@ -3707,7 +3707,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); manipulating bit strings, that is values of the types bit and bit varying. Aside from the usual comparison operators, the operators - shown in can be used. + shown in can be used. Bit string operands of &, |, and # must be of equal length. When bit shifting, the original length of the string is preserved, as shown @@ -3935,9 +3935,9 @@ cast(-44 as bit(12)) 111111010100 - If you have turned off, + If you have turned off, any backslashes you write in literal string constants will need to be - doubled. See for more information. + doubled. See for more information. @@ -4144,7 +4144,7 @@ substring('foobar' from '#"o_b#"%' for '#') NULL - lists the available + lists the available operators for pattern matching using POSIX regular expressions. @@ -4277,7 +4277,7 @@ substring('foobar' from 'o(.)b') o matching, while flag g specifies replacement of each matching substring rather than only the first one. Supported flags (though not g) are - described in . + described in . @@ -4311,7 +4311,7 @@ regexp_replace('foobarbaz', 'b(..)', E'X\\1Y', 'g') The flags parameter is an optional text string containing zero or more single-letter flags that change the function's behavior. Supported flags are described - in . + in . @@ -4353,7 +4353,7 @@ SELECT (regexp_match('foobarbequebaz', 'bar.*que'))[1]; subexpressions of the pattern, just as described above for regexp_match. regexp_matches accepts all the flags shown - in , plus + in , plus the g flag which commands it to return all matches, not just the first one. @@ -4407,7 +4407,7 @@ SELECT col1, (SELECT regexp_matches(col2, '(bar)(beque)')) FROM tab; The flags parameter is an optional text string containing zero or more single-letter flags that change the function's behavior. regexp_split_to_table supports the flags described in - . + . @@ -4513,7 +4513,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; PostgreSQL always initially presumes that a regular expression follows the ARE rules. However, the more limited ERE or BRE rules can be chosen by prepending an embedded option - to the RE pattern, as described in . + to the RE pattern, as described in . This can be useful for compatibility with applications that expect exactly the POSIX 1003.2 rules. @@ -4539,9 +4539,9 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; Without a quantifier, it matches a match for the atom. With a quantifier, it can match some number of matches of the atom. An atom can be any of the possibilities - shown in . + shown in . The possible quantifiers and their meanings are shown in - . + . @@ -4549,7 +4549,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; specific conditions are met. A constraint can be used where an atom could be used, except it cannot be followed by a quantifier. The simple constraints are shown in - ; + ; some more constraints are described later. @@ -4589,7 +4589,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; [chars] a bracket expression, matching any one of the chars (see - for more detail) + for more detail) @@ -4603,7 +4603,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; \c where c is alphanumeric (possibly followed by other characters) - is an escape, see + is an escape, see (AREs only; in EREs and BREs, this matches c) @@ -4630,9 +4630,9 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; - If you have turned off, + If you have turned off, any backslashes you write in literal string constants will need to be - doubled. See for more information. + doubled. See for more information. @@ -4727,7 +4727,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; same possibilities as their corresponding normal (greedy) counterparts, but prefer the smallest number rather than the largest number of matches. - See for more detail. + See for more detail. @@ -4795,7 +4795,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; Lookahead and lookbehind constraints cannot contain back - references (see ), + references (see ), and all parentheses within them are considered non-capturing. @@ -4926,27 +4926,27 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; Character-entry escapes exist to make it easier to specify non-printing and other inconvenient characters in REs. They are - shown in . + shown in . Class-shorthand escapes provide shorthands for certain commonly-used character classes. They are - shown in . + shown in . A constraint escape is a constraint, matching the empty string if specific conditions are met, written as an escape. They are - shown in . + shown in . A back reference (\n) matches the same string matched by the previous parenthesized subexpression specified by the number n - (see ). For example, + (see ). For example, ([bc])\1 matches bb or cc but not bc or cb. The subexpression must entirely precede the back reference in the RE. @@ -5167,7 +5167,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; \A matches only at the beginning of the string - (see for how this differs from + (see for how this differs from ^) @@ -5195,7 +5195,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; \Z matches only at the end of the string - (see for how this differs from + (see for how this differs from $) @@ -5284,7 +5284,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; a regex operator, or the flags parameter to a regex function. The available option letters are - shown in . + shown in . Note that these same option letters are used in the flags parameters of regex functions. @@ -5319,7 +5319,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; i case-insensitive matching (see - ) (overrides operator type) + ) (overrides operator type) @@ -5330,13 +5330,13 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; n newline-sensitive matching (see - ) + ) p partial newline-sensitive matching (see - ) + ) @@ -5358,7 +5358,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; w inverse partial newline-sensitive (weird) matching - (see ) + (see ) @@ -5735,7 +5735,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); provide a powerful set of tools for converting various data types (date/time, integer, floating point, numeric) to formatted strings and for converting from formatted strings to specific data types. - lists them. + lists them. These functions all follow a common calling convention: the first argument is the value to be formatted and the second argument is a template that defines the output or input format. @@ -5829,7 +5829,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); There is also a single-argument to_timestamp - function; see . + function; see . @@ -5857,7 +5857,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); - shows the + shows the template patterns available for formatting date and time values. @@ -6087,7 +6087,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); behavior. For example, FMMonth is the Month pattern with the FM modifier. - shows the + shows the modifier patterns for date/time formatting. @@ -6125,7 +6125,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); TM prefix translation mode (print localized day and month names based on - ) + ) TMMonth @@ -6291,7 +6291,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); specifications like YYYY-MM-DD (IYYY-IDDD) can be useful. But avoid writing something like IYYY-MM-DD; that would yield surprising results near the start of the year. - (See for more + (See for more information.) @@ -6345,7 +6345,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); - shows the + shows the template patterns available for formatting numeric values. @@ -6447,8 +6447,8 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); The pattern characters S, L, D, and G represent the sign, currency symbol, decimal point, and thousands separator characters defined by the current locale - (see - and ). The pattern characters period + (see + and ). The pattern characters period and comma represent those exact characters, with the meanings of decimal point and thousands separator, regardless of locale. @@ -6535,7 +6535,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); behavior. For example, FM99.99 is the 99.99 pattern with the FM modifier. - shows the + shows the modifier patterns for numeric formatting. @@ -6570,7 +6570,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
- shows some + shows some examples of the use of the to_char function. @@ -6747,15 +6747,15 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); Date/Time Functions and Operators - shows the available + shows the available functions for date/time value processing, with details appearing in the following subsections. illustrates the behaviors of + linkend="operators-datetime-table"/> illustrates the behaviors of the basic arithmetic operators (+, *, etc.). For formatting functions, refer to - . You should be familiar with + . You should be familiar with the background information on date/time data types from . + linkend="datatype-datetime"/>. @@ -6943,7 +6943,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); timestamp with time zone Current date and time (changes during statement execution); - see + see @@ -6958,7 +6958,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); date Current date; - see + see @@ -6973,7 +6973,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); time with time zone Current time of day; - see + see @@ -6988,7 +6988,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); timestamp with time zone Current date and time (start of current transaction); - see + see @@ -7003,7 +7003,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); double precision Get subfield (equivalent to extract); - see + see date_part('hour', timestamp '2001-02-16 20:38:40') 20 @@ -7013,7 +7013,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); date_part(text, interval) double precision Get subfield (equivalent to - extract); see + extract); see date_part('month', interval '2 years 3 months') 3 @@ -7027,7 +7027,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); date_trunc(text, timestamp) timestamp - Truncate to specified precision; see also + Truncate to specified precision; see also date_trunc('hour', timestamp '2001-02-16 20:38:40') 2001-02-16 20:00:00 @@ -7036,7 +7036,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); date_trunc(text, interval) interval - Truncate to specified precision; see also + Truncate to specified precision; see also date_trunc('hour', interval '2 days 3 hours 40 minutes') 2 days 03:00:00 @@ -7051,7 +7051,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); timestamp) double precision - Get subfield; see + Get subfield; see extract(hour from timestamp '2001-02-16 20:38:40') 20 @@ -7061,7 +7061,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); extract(field from interval) double precision - Get subfield; see + Get subfield; see extract(month from interval '2 years 3 months') 3 @@ -7144,7 +7144,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); time Current time of day; - see + see @@ -7159,7 +7159,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); timestamp Current date and time (start of current transaction); - see + see @@ -7293,7 +7293,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); timestamp with time zone Current date and time (start of current transaction); - see + see @@ -7308,7 +7308,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); timestamp with time zone Current date and time (start of current statement); - see + see @@ -7324,7 +7324,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); text Current date and time (like clock_timestamp, but as a text string); - see + see @@ -7339,7 +7339,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}'); timestamp with time zone Current date and time (start of current transaction); - see + see @@ -7886,7 +7886,7 @@ SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40'); The extract function is primarily intended for computational processing. For formatting date/time values for - display, see . + display, see . @@ -7986,7 +7986,7 @@ SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40'); The AT TIME ZONE construct allows conversions of time stamps to different time zones. shows its + linkend="functions-datetime-zoneconvert-table"/> shows its variants. @@ -8035,7 +8035,7 @@ SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40'); specified either as a text string (e.g., 'PST') or as an interval (e.g., INTERVAL '-08:00'). In the text case, a time zone name can be specified in any of the ways - described in . + described in . @@ -8279,10 +8279,10 @@ SELECT pg_sleep_until('tomorrow 03:00'); Enum Support Functions - For enum types (described in ), + For enum types (described in ), there are several functions that allow cleaner programming without hard-coding particular values of an enum type. - These are listed in . The examples + These are listed in . The examples assume an enum type created as: @@ -8379,9 +8379,9 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple lseg, line, path, polygon, and circle have a large set of native support functions and operators, shown in , , and . + linkend="functions-geometry-op-table"/>, , and . @@ -8912,7 +8912,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple Network Address Functions and Operators - shows the operators + shows the operators available for the cidr and inet types. The operators <<, <<=, >>, @@ -9024,7 +9024,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - shows the functions + shows the functions available for use with the cidr and inet types. The abbrev, host, and text @@ -9225,7 +9225,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - shows the functions + shows the functions available for use with the macaddr type. The function trunc(macaddr) returns a MAC address with the last 3 bytes set to zero. This can be used to @@ -9270,7 +9270,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - shows the functions + shows the functions available for use with the macaddr8 type. The function trunc(macaddr8) returns a MAC address with the last 5 bytes set to zero. This can be used to @@ -9342,11 +9342,11 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - , - and - + , + and + summarize the functions and operators that are provided - for full text searching. See for a detailed + for full text searching. See for a detailed explanation of PostgreSQL's text search facility. @@ -9797,14 +9797,14 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple All the text search functions that accept an optional regconfig argument will use the configuration specified by - + when that argument is omitted. The functions in - + are listed separately because they are not usually used in everyday text searching operations. They are helpful for development and debugging of new text search configurations. @@ -9910,7 +9910,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple The functions and function-like expressions described in this section operate on values of type xml. Check for information about the xml + linkend="datatype-xml"/> for information about the xml type. The function-like expressions xmlparse and xmlserialize for converting to and from type xml are not repeated here. Use of most of these @@ -10107,7 +10107,7 @@ SELECT xmlelement(name foo, xmlattributes('xyz' as bar), and & will be converted to entities. Binary data (data type bytea) will be represented in base64 or hex encoding, depending on the setting of the configuration parameter - . The particular behavior for + . The particular behavior for individual data types is expected to evolve in order to align the SQL and PostgreSQL data types with the XML Schema specification, at which point a more precise description will appear. @@ -10249,7 +10249,7 @@ SELECT xmlroot(xmlparse(document 'abc'), input values to the aggregate function call, much like xmlconcat does, except that concatenation occurs across rows rather than across expressions in a single row. - See for additional information + See for additional information about aggregate functions. @@ -10269,7 +10269,7 @@ SELECT xmlagg(x) FROM test; To determine the order of the concatenation, an ORDER BY clause may be added to the aggregate call as described in - . For example: + . For example: IS DOCUMENT returns true if the argument XML value is a proper XML document, false if it is not (that is, it is a content fragment), or null if the argument is - null. See about the difference + null. See about the difference between documents and content fragments. @@ -10391,7 +10391,7 @@ SELECT xmlexists('//town[text() = ''Toronto'']' PASSING BY REF 'Tor xml_is_well_formed_document checks for a well-formed document, while xml_is_well_formed_content checks for well-formed content. xml_is_well_formed does - the former if the configuration + the former if the configuration parameter is set to DOCUMENT, or the latter if it is set to CONTENT. This means that xml_is_well_formed is useful for seeing whether @@ -10975,7 +10975,7 @@ table2-mapping As an example of using the output produced by these functions, - shows an XSLT stylesheet that + shows an XSLT stylesheet that converts the output of table_to_xml_and_xmlschema to an HTML document containing a tabular rendition of the table data. In a @@ -11044,9 +11044,9 @@ table2-mapping - shows the operators that + shows the operators that are available for use with the two JSON data types (see ). + linkend="datatype-json"/>). @@ -11127,18 +11127,18 @@ table2-mapping The standard comparison operators shown in are available for + linkend="functions-comparison-op-table"/> are available for jsonb, but not for json. They follow the ordering rules for B-tree operations outlined at . + linkend="json-indexing"/>. Some further operators also exist only for jsonb, as shown - in . + in . Many of these operators can be indexed by jsonb operator classes. For a full description of jsonb containment and existence semantics, see . + linkend="json-containment"/>. describes how these operators can be used to effectively index jsonb data. @@ -11240,7 +11240,7 @@ table2-mapping - shows the functions that are + shows the functions that are available for creating json and jsonb values. (There are no equivalent functions for jsonb, of the row_to_json and array_to_json functions. However, the to_jsonb @@ -11394,7 +11394,7 @@ table2-mapping - The extension has a cast + The extension has a cast from hstore to json, so that hstore values converted via the JSON creation functions will be represented as JSON objects, not as primitive string values. @@ -11402,7 +11402,7 @@ table2-mapping - shows the functions that + shows the functions that are available for processing json and jsonb values. @@ -11843,7 +11843,7 @@ table2-mapping JSON strings to the appropriate single character. This is a non-issue if the input is type jsonb, because the conversion was already done; but for json input, this may result in throwing an error, - as noted in . + as noted in . @@ -11902,7 +11902,7 @@ table2-mapping - See also for the aggregate + See also for the aggregate function json_agg which aggregates record values as JSON, and the aggregate function json_object_agg which aggregates pairs of values @@ -11935,10 +11935,10 @@ table2-mapping This section describes functions for operating on sequence objects, also called sequence generators or just sequences. Sequence objects are special single-row tables created with . + linkend="sql-createsequence"/>. Sequence objects are commonly used to generate unique identifiers for rows of a table. The sequence functions, listed in , provide simple, multiuser-safe + linkend="functions-sequence-table"/>, provide simple, multiuser-safe methods for obtaining successive sequence values from sequence objects. @@ -12003,7 +12003,7 @@ nextval('myschema.foo') operates on myschema.foosame as above nextval('foo') searches search path for foo - See for more information about + See for more information about regclass. @@ -12061,7 +12061,7 @@ nextval('foo'::text) foo is looked up at If a sequence object has been created with default parameters, successive nextval calls will return successive values beginning with 1. Other behaviors can be obtained by using - special parameters in the command; + special parameters in the command; see its command reference page for more information. @@ -12262,7 +12262,7 @@ SELECT a, The data types of all the result expressions must be convertible to a single output type. - See for more details. + See for more details. @@ -12316,7 +12316,7 @@ SELECT ... WHERE CASE WHEN x <> 0 THEN y/x > 1.5 ELSE false END; - As described in , there are various + As described in , there are various situations in which subexpressions of an expression are evaluated at different times, so that the principle that CASE evaluates only necessary subexpressions is not ironclad. For @@ -12419,7 +12419,7 @@ SELECT NULLIF(value, '(none)') ... largest or smallest value from a list of any number of expressions. The expressions must all be convertible to a common data type, which will be the type of the result - (see for details). NULL values + (see for details). NULL values in the list are ignored. The result will be NULL only if all the expressions evaluate to NULL. @@ -12437,7 +12437,7 @@ SELECT NULLIF(value, '(none)') ... Array Functions and Operators - shows the operators + shows the operators available for array types. @@ -12561,14 +12561,14 @@ SELECT NULLIF(value, '(none)') ... - See for more details about array operator - behavior. See for more details about + See for more details about array operator + behavior. See for more details about which operators support indexed operations. - shows the functions - available for use with array types. See + shows the functions + available for use with array types. See for more information and examples of the use of these functions. @@ -12843,7 +12843,7 @@ SELECT NULLIF(value, '(none)') ... setof anyelement, anyelement [, ...] expand multiple arrays (possibly of different types) to a set of rows. This is only allowed in the FROM clause; see - + unnest(ARRAY[1,2],ARRAY['foo','bar','baz']) 1 foo 2 bar @@ -12899,7 +12899,7 @@ NULL baz(3 rows) - See also about the aggregate + See also about the aggregate function array_agg for use with arrays. @@ -12908,11 +12908,11 @@ NULL baz(3 rows) Range Functions and Operators - See for an overview of range types. + See for an overview of range types. - shows the operators + shows the operators available for range types. @@ -13087,7 +13087,7 @@ NULL baz(3 rows) - shows the functions + shows the functions available for use with range types. @@ -13238,18 +13238,18 @@ NULL baz(3 rows) Aggregate functions compute a single result from a set of input values. The built-in general-purpose aggregate - functions are listed in + functions are listed in and statistical aggregates in . + linkend="functions-aggregate-statistics-table"/>. The built-in within-group ordered-set aggregate functions - are listed in + are listed in while the built-in within-group hypothetical-set ones are in . Grouping operations, + linkend="functions-hypothetical-table"/>. Grouping operations, which are closely related to aggregate functions, are listed in - . + . The special syntax considerations for aggregate - functions are explained in . - Consult for additional introductory + functions are explained in . + Consult for additional introductory information. @@ -13597,7 +13597,7 @@ NULL baz(3 rows) xml No - concatenation of XML values (see also ) + concatenation of XML values (see also ) @@ -13669,7 +13669,7 @@ SELECT count(*) FROM sometable; depending on the order of the input values. This ordering is unspecified by default, but can be controlled by writing an ORDER BY clause within the aggregate call, as shown in - . + . Alternatively, supplying the input values from a sorted subquery will usually work. For example: @@ -13683,7 +13683,7 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; - shows + shows aggregate functions typically used in statistical analysis. (These are separated out merely to avoid cluttering the listing of more-commonly-used aggregates.) Where the description mentions @@ -14102,7 +14102,7 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab;
- shows some + shows some aggregate functions that use the ordered-set aggregate syntax. These functions are sometimes referred to as inverse distribution functions. @@ -14252,7 +14252,7 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; - All the aggregates listed in + All the aggregates listed in ignore null values in their sorted input. For those that take a fraction parameter, the fraction value must be between 0 and 1; an error is thrown if not. However, a null fraction value @@ -14266,9 +14266,9 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; Each of the aggregates listed in - is associated with a + is associated with a window function of the same name defined in - . In each case, the aggregate result + . In each case, the aggregate result is the value that the associated window function would have returned for the hypothetical row constructed from args, if such a row had been added to the sorted @@ -14433,7 +14433,7 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; Grouping operations are used in conjunction with grouping sets (see - ) to distinguish result rows. The + ) to distinguish result rows. The arguments to the GROUPING operation are not actually evaluated, but they must match exactly expressions given in the GROUP BY clause of the associated query level. Bits are assigned with the rightmost @@ -14477,14 +14477,14 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; Window functions provide the ability to perform calculations across sets of rows that are related to the current query - row. See for an introduction to this - feature, and for syntax + row. See for an introduction to this + feature, and for syntax details. The built-in window functions are listed in - . Note that these functions + . Note that these functions must be invoked using window function syntax, i.e., an OVER clause is required. @@ -14494,7 +14494,7 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; general-purpose or statistical aggregate (i.e., not ordered-set or hypothetical-set aggregates) can be used as a window function; see - for a list of the built-in aggregates. + for a list of the built-in aggregates. Aggregate functions act as window functions only when an OVER clause follows the call; otherwise they act as non-window aggregates and return a single row for the entire set. @@ -14706,7 +14706,7 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; All of the functions listed in - depend on the sort ordering + depend on the sort ordering specified by the ORDER BY clause of the associated window definition. Rows that are not distinct when considering only the ORDER BY columns are said to be peers. @@ -14723,7 +14723,7 @@ SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab; sometimes also nth_value. You can redefine the frame by adding a suitable frame specification (RANGE or ROWS) to the OVER clause. - See for more information + See for more information about frame specifications. @@ -14887,7 +14887,7 @@ WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2); The left-hand side of this form of IN is a row constructor, - as described in . + as described in . The right-hand side is a parenthesized subquery, which must return exactly as many columns as there are expressions in the left-hand row. The left-hand expressions are @@ -14943,7 +14943,7 @@ WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2); The left-hand side of this form of NOT IN is a row constructor, - as described in . + as described in . The right-hand side is a parenthesized subquery, which must return exactly as many columns as there are expressions in the left-hand row. The left-hand expressions are @@ -15008,7 +15008,7 @@ WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2); The left-hand side of this form of ANY is a row constructor, - as described in . + as described in . The right-hand side is a parenthesized subquery, which must return exactly as many columns as there are expressions in the left-hand row. The left-hand expressions are @@ -15024,7 +15024,7 @@ WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2); - See for details about the meaning + See for details about the meaning of a row constructor comparison. @@ -15064,7 +15064,7 @@ WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2); The left-hand side of this form of ALL is a row constructor, - as described in . + as described in . The right-hand side is a parenthesized subquery, which must return exactly as many columns as there are expressions in the left-hand row. The left-hand expressions are @@ -15080,7 +15080,7 @@ WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2); - See for details about the meaning + See for details about the meaning of a row constructor comparison. @@ -15099,7 +15099,7 @@ WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2); The left-hand side is a row constructor, - as described in . + as described in . The right-hand side is a parenthesized subquery, which must return exactly as many columns as there are expressions in the left-hand row. Furthermore, the subquery cannot return more than one row. (If it returns zero rows, @@ -15108,7 +15108,7 @@ WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2); - See for details about the meaning + See for details about the meaning of a row constructor comparison. @@ -15327,7 +15327,7 @@ AND Each side is a row constructor, - as described in . + as described in . The two row values must have the same number of fields. Each side is evaluated and they are compared row-wise. Row constructor comparisons are allowed when the operator is @@ -15419,8 +15419,8 @@ AND result depends on comparing two NULL values or a NULL and a non-NULL. PostgreSQL does this only when comparing the results of two row constructors (as in - ) or comparing a row constructor - to the output of a subquery (as in ). + ) or comparing a row constructor + to the output of a subquery (as in ). In other contexts where two composite-type values are compared, two NULL field values are considered equal, and a NULL is considered larger than a non-NULL. This is necessary in order to have consistent sorting @@ -15441,7 +15441,7 @@ AND class, or is the negator of the = member of a B-tree operator class.) The default behavior of the above operators is the same as for IS [ NOT ] DISTINCT FROM for row constructors (see - ). + ). @@ -15481,10 +15481,10 @@ AND This section describes functions that possibly return more than one row. The most widely used functions in this class are series generating - functions, as detailed in and - . Other, more specialized + functions, as detailed in and + . Other, more specialized set-returning functions are described elsewhere in this manual. - See for ways to combine multiple + See for ways to combine multiple set-returning functions. @@ -15738,14 +15738,14 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n); System Information Functions - shows several + shows several functions that extract session and system information. In addition to the functions listed in this section, there are a number of functions related to the statistics system that also provide system - information. See for more + information. See for more information. @@ -15910,7 +15910,7 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n); version() text - PostgreSQL version information. See also for a machine-readable version. + PostgreSQL version information. See also for a machine-readable version. @@ -15988,11 +15988,11 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n); The session_user is normally the user who initiated the current database connection; but superusers can change this setting - with . + with . The current_user is the user identifier that is applicable for permission checking. Normally it is equal to the session user, but it can be changed with - . + . It also changes during the execution of functions with the attribute SECURITY DEFINER. In Unix parlance, the session user is the real user and @@ -16111,7 +16111,7 @@ SET search_path TO schema , sc pg_current_logfile returns, as text, the path of the log file(s) currently in use by the logging collector. - The path includes the directory + The path includes the directory and the log file name. Log collection must be enabled or the return value is NULL. When multiple log files exist, each in a different format, pg_current_logfile called @@ -16122,7 +16122,7 @@ SET search_path TO schema , sc either csvlog or stderr as the value of the optional parameter. The return value is NULL when the log format requested is not a configured - . The + . The pg_current_logfiles reflects the contents of the current_logfiles file. @@ -16160,7 +16160,7 @@ SET search_path TO schema , sc fraction of the total available space for notifications currently occupied by notifications that are waiting to be processed, as a double in the range 0-1. - See and + See and for more information. @@ -16186,7 +16186,7 @@ SET search_path TO schema , sc running a SERIALIZABLE transaction blocks a SERIALIZABLE READ ONLY DEFERRABLE transaction from acquiring a snapshot until the latter determines that it is safe to avoid - taking any predicate locks. See for + taking any predicate locks. See for more information about serializable and deferrable transactions. Frequent calls to this function could have some impact on database performance, because it needs access to the predicate lock manager's shared @@ -16200,10 +16200,10 @@ SET search_path TO schema , sc version returns a string describing the PostgreSQL server's version. You can also - get this information from or - for a machine-readable version, . + get this information from or + for a machine-readable version, . Software developers should use server_version_num - (available since 8.2) or instead + (available since 8.2) or instead of parsing the text version. @@ -16213,9 +16213,9 @@ SET search_path TO schema , sc - lists functions that + lists functions that allow the user to query object access privileges programmatically. - See for more information about + See for more information about privileges. @@ -16569,7 +16569,7 @@ SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION') are analogous to has_table_privilege. When specifying a function by a text string rather than by OID, the allowed input is the same as for the regprocedure data type - (see ). + (see ). The desired access privilege type must evaluate to EXECUTE. An example is: @@ -16631,7 +16631,7 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); are analogous to has_table_privilege. When specifying a type by a text string rather than by OID, the allowed input is the same as for the regtype data type - (see ). + (see ). The desired access privilege type must evaluate to USAGE. @@ -16659,7 +16659,7 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); - shows functions that + shows functions that determine whether a certain object is visible in the current schema search path. For example, a table is said to be visible if its @@ -16957,7 +16957,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); - lists functions that + lists functions that extract information from the system catalogs. @@ -17250,7 +17250,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); second parameter, being just a column name, is treated as double-quoted and has its case preserved. The function returns a value suitably formatted for passing to sequence functions - (see ). A typical use is in reading the + (see ). A typical use is in reading the current value of a sequence for an identity or serial column, for example: SELECT currval(pg_get_serial_sequence('sometable', 'id')); @@ -17270,9 +17270,9 @@ SELECT currval(pg_get_serial_sequence('sometable', 'id')); property. NULL is returned if the property name is not known or does not apply to the particular object, or if the OID or column number does not identify a valid object. Refer to - for column properties, - for index properties, and - for access method properties. + for column properties, + for index properties, and + for access method properties. (Note that extension access methods can define additional property names for their indexes.) @@ -17423,7 +17423,7 @@ SELECT currval(pg_get_serial_sequence('sometable', 'id')); value that is passed to it. This can be helpful for troubleshooting or dynamically constructing SQL queries. The function is declared as returning regtype, which is an OID alias type (see - ); this means that it is the same as an + ); this means that it is the same as an OID for comparison purposes but displays as a type name. For example: SELECT pg_typeof(33); @@ -17496,7 +17496,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); - lists functions related to + lists functions related to database object identification and addressing. @@ -17603,8 +17603,8 @@ SELECT collation for ('foo' COLLATE "de_DE"); - The functions shown in - extract comments previously stored with the + The functions shown in + extract comments previously stored with the command. A null value is returned if no comment could be found for the specified parameters. @@ -17701,7 +17701,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); - The functions shown in + The functions shown in provide server transaction information in an exportable form. The main use of these functions is to determine which transactions were committed between two snapshots. @@ -17767,7 +17767,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); The data type used by these functions, txid_snapshot, stores information about transaction ID visibility at a particular moment in time. Its components are - described in . + described in . @@ -17843,11 +17843,11 @@ SELECT collation for ('foo' COLLATE "de_DE"); - The functions shown in + The functions shown in provide information about transactions that have been already committed. These functions mainly provide information about when the transactions were committed. They only provide useful data when - configuration option is enabled + configuration option is enabled and only for transactions that were committed after it was enabled. @@ -17881,13 +17881,13 @@ SELECT collation for ('foo' COLLATE "de_DE");
- The functions shown in + The functions shown in print information initialized during initdb, such as the catalog version. They also show information about write-ahead logging and checkpoint processing. This information is cluster-wide, and not specific to any one database. They provide most of the same information, from the same source, as - , although in a form better suited + , although in a form better suited to SQL functions. @@ -17949,7 +17949,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); pg_control_checkpoint returns a record, shown in - + @@ -18060,7 +18060,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); pg_control_system returns a record, shown in - +
@@ -18101,7 +18101,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); pg_control_init returns a record, shown in - +
@@ -18182,7 +18182,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); pg_control_recovery returns a record, shown in - +
@@ -18240,7 +18240,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); Configuration Settings Functions - shows the functions + shows the functions available to query and alter run-time configuration parameters. @@ -18356,7 +18356,7 @@ SELECT set_config('log_statement_stats', 'off', false); The functions shown in send control signals to + linkend="functions-admin-signal-table"/> send control signals to other server processes. Use of these functions is restricted to superusers by default but access may be granted to others using GRANT, with noted exceptions. @@ -18491,7 +18491,7 @@ SELECT set_config('log_statement_stats', 'off', false); The functions shown in assist in making on-line backups. + linkend="functions-admin-backup-table"/> assist in making on-line backups. These functions cannot be executed during recovery (except pg_is_in_backup, pg_backup_start_time and pg_wal_lsn_diff). @@ -18674,7 +18674,7 @@ postgres=# select pg_start_backup('label_goes_here'); pg_create_restore_point creates a named write-ahead log record that can be used as recovery target, and returns the corresponding write-ahead log location. The given name can then be used with - to specify the point up to which + to specify the point up to which recovery will proceed. Avoid creating multiple restore points with the same name, since recovery will stop at the first one whose name matches the recovery target. @@ -18719,12 +18719,12 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); pg_wal_lsn_diff calculates the difference in bytes between two write-ahead log locations. It can be used with pg_stat_replication or some functions shown in - to get the replication lag. + to get the replication lag. For details about proper usage of these functions, see - . + . @@ -18747,7 +18747,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); The functions shown in provide information + linkend="functions-recovery-info-table"/> provide information about the current status of the standby. These functions may be executed both during recovery and in normal running. @@ -18828,7 +18828,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); The functions shown in control the progress of recovery. + linkend="functions-recovery-control-table"/> control the progress of recovery. These functions may be executed only during recovery. @@ -18919,8 +18919,8 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); Snapshots are exported with the pg_export_snapshot function, - shown in , and - imported with the command. + shown in , and + imported with the command.
@@ -18953,11 +18953,11 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); COMMITTED transactions, since in REPEATABLE READ and higher isolation levels, transactions use the same snapshot throughout their lifetime. Once a transaction has exported any snapshots, it cannot - be prepared with . + be prepared with . - See for details of how to use an + See for details of how to use an exported snapshot. @@ -18967,25 +18967,25 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); The functions shown - in are for + in are for controlling and interacting with replication features. - See , - , and - + See , + , and + for information about the underlying features. Use of these functions is restricted to superusers. Many of these functions have equivalent commands in the replication - protocol; see . + protocol; see . The functions described in - , - , and - + , + , and + are also relevant for replication. @@ -19018,7 +19018,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); the LSN is reserved on first connection from a streaming replication client. Streaming changes from a physical slot is only possible with the streaming-replication protocol — - see . The optional third + see . The optional third parameter, temporary, when set to true, specifies that the slot should not be permanently stored to disk and is only meant for use by current session. Temporary slots are also @@ -19386,7 +19386,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); Database Object Management Functions - The functions shown in calculate + The functions shown in calculate the disk space usage of database objects. @@ -19598,13 +19598,13 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); 'fsm' returns the size of the Free Space Map - (see ) associated with the relation. + (see ) associated with the relation. 'vm' returns the size of the Visibility Map - (see ) associated with the relation. + (see ) associated with the relation. @@ -19656,7 +19656,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); - The functions shown in assist + The functions shown in assist in identifying the specific disk files associated with database objects. @@ -19714,7 +19714,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); pg_relation_filenode accepts the OID or name of a table, index, sequence, or toast table, and returns the filenode number currently assigned to it. The filenode is the base component of the file - name(s) used for the relation (see + name(s) used for the relation (see for more information). For most tables the result is the same as pg_class.relfilenode, but for certain system catalogs relfilenode is zero and this function must @@ -19737,7 +19737,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); - lists functions used to manage + lists functions used to manage collations. @@ -19775,7 +19775,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); operating system. If this is different from the value in pg_collation.collversion, then objects depending on the collation might need to be rebuilt. See also - . + . @@ -19783,7 +19783,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); catalog pg_collation based on all the locales it finds in the operating system. This is what initdb uses; - see for more details. If additional + see for more details. If additional locales are installed into the operating system later on, this function can be run again to add collations for the new locales. Locales that match existing entries in pg_collation will be skipped. @@ -19817,7 +19817,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); - shows the functions + shows the functions available for index maintenance tasks. These functions cannot be executed during recovery. Use of these functions is restricted to superusers and the owner @@ -19882,7 +19882,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); Note that if the argument is a GIN index built with the fastupdate option disabled, no cleanup happens and the return value is 0, because the index doesn't have a pending list. - Please see and + Please see and for details of the pending list and fastupdate option. @@ -19893,7 +19893,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); The functions shown in provide native access to + linkend="functions-admin-genfile-table"/> provide native access to files on the machine hosting the server. Only files within the database cluster directory and the log_directory can be accessed. Use a relative path for files in the cluster directory, @@ -20064,9 +20064,9 @@ SELECT (pg_stat_file('filename')).modification; Advisory Lock Functions - The functions shown in + The functions shown in manage advisory locks. For details about proper use of these functions, - see . + see .
@@ -20392,7 +20392,7 @@ FOR EACH ROW EXECUTE PROCEDURE suppress_redundant_updates_trigger(); For more information about creating triggers, see - . + . @@ -20406,7 +20406,7 @@ FOR EACH ROW EXECUTE PROCEDURE suppress_redundant_updates_trigger(); For more information about event triggers, - see . + see . @@ -20645,7 +20645,7 @@ CREATE EVENT TRIGGER test_event_trigger_for_drops The functions shown in - + provide information about a table for which a table_rewrite event has just been called. If called in any other context, an error is raised. diff --git a/doc/src/sgml/geqo.sgml b/doc/src/sgml/geqo.sgml index 0f91272c54..5120dfbb42 100644 --- a/doc/src/sgml/geqo.sgml +++ b/doc/src/sgml/geqo.sgml @@ -237,7 +237,7 @@ choices made during both the initial population selection and subsequent mutation of the best candidates. To avoid surprising changes of the selected plan, each run of the GEQO algorithm restarts its - random number generator with the current + random number generator with the current parameter setting. As long as geqo_seed and the other GEQO parameters are kept fixed, the same plan will be generated for a given query (and other planner inputs such as statistics). To experiment @@ -320,13 +320,13 @@ - + - + diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml index 95d6278d28..cc7cd1ed2c 100644 --- a/doc/src/sgml/gin.sgml +++ b/doc/src/sgml/gin.sgml @@ -68,8 +68,8 @@ The core PostgreSQL distribution includes the GIN operator classes shown in - . - (Some of the optional modules described in + . + (Some of the optional modules described in provide additional GIN operator classes.) @@ -127,7 +127,7 @@ Of the two operator classes for type jsonb, jsonb_ops is the default. jsonb_path_ops supports fewer operators but offers better performance for those operators. - See for details. + See for details. @@ -182,7 +182,7 @@ query is the value on the right-hand side of an indexable operator whose left-hand side is the indexed column. n is the strategy number of the operator within the - operator class (see ). + operator class (see ). Often, extractQuery will need to consult n to determine the data type of query and the method it should use to extract key values. @@ -406,7 +406,7 @@ provide the comparePartial method, and its extractQuery method must set the pmatch parameter when a partial-match query is encountered. See - for details. + for details. @@ -466,7 +466,7 @@ When the table is vacuumed or autoanalyzed, or when gin_clean_pending_list function is called, or if the pending list becomes larger than - , the entries are moved to the + , the entries are moved to the main GIN data structure using the same bulk insert techniques used during initial index creation. This greatly improves GIN index update speed, even counting the additional @@ -488,7 +488,7 @@ If consistent response time is more important than update speed, use of pending entries can be disabled by turning off the fastupdate storage parameter for a - GIN index. See + GIN index. See for details. @@ -531,14 +531,14 @@ As of PostgreSQL 8.4, this advice is less necessary since delayed indexing is used (see 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. - + Build time for a GIN index is very sensitive to @@ -549,7 +549,7 @@ - + During a series of insertions into an existing GIN @@ -574,7 +574,7 @@ - + The primary goal of developing GIN indexes was @@ -631,7 +631,7 @@ The core PostgreSQL distribution includes the GIN operator classes previously shown in - . + . The following contrib modules also contain GIN operator classes: diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml index f2f9ca0853..44a3b2c03c 100644 --- a/doc/src/sgml/gist.sgml +++ b/doc/src/sgml/gist.sgml @@ -46,8 +46,8 @@ The core PostgreSQL distribution includes the GiST operator classes shown in - . - (Some of the optional modules described in + . + (Some of the optional modules described in provide additional GiST operator classes.) @@ -985,7 +985,7 @@ my_fetch(PG_FUNCTION_ARGS) By default, a GiST index build switches to the buffering method when the - index size reaches . It can + index size reaches . It can be manually turned on or off by the buffering parameter 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 diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index 6c0679b0a8..46bf198a2a 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -100,7 +100,7 @@ Shared hardware functionality is common in network storage devices. Using a network file system is also possible, though care must be taken that the file system has full POSIX behavior (see ). 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 primary and standby servers are both nonfunctional. Another issue is 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. A standby server can be implemented using file-based log shipping - () or streaming replication (see - ), or a combination of both. For - information on hot standby, see . + () or streaming replication (see + ), or a combination of both. For + information on hot standby, see . @@ -169,8 +169,8 @@ protocol to make nodes agree on a serializable transactional order. individual tables to be replicated. Logical replication doesn't require 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 - replication, see . Through the - logical decoding interface (), + replication, see . Through the + logical decoding interface (), third-party extensions can also provide similar functionality. @@ -224,8 +224,8 @@ protocol to make nodes agree on a serializable transactional order. standby servers via master-standby replication, not by the replication middleware. Care must also be taken that all transactions either commit or abort on all servers, perhaps - using two-phase commit ( - and ). + using two-phase commit ( + and ). Pgpool-II and Continuent Tungsten are examples of this type of replication. @@ -272,8 +272,8 @@ protocol to make nodes agree on a serializable transactional order. PostgreSQL does not offer this type of replication, though PostgreSQL two-phase commit ( and ) + linkend="sql-prepare-transaction"/> and ) can be used to implement this in application code or middleware. @@ -295,7 +295,7 @@ protocol to make nodes agree on a serializable transactional order. - summarizes + summarizes the capabilities of the various solutions listed above. @@ -522,7 +522,7 @@ protocol to make nodes agree on a serializable transactional order. varies according to the transaction rate of the primary server. Record-based log shipping is more granular and streams WAL changes incrementally over a network connection (see ). + linkend="streaming-replication"/>). @@ -534,7 +534,7 @@ protocol to make nodes agree on a serializable transactional order. archive_timeout parameter, which can be set as low as a few seconds. However such a low setting will substantially increase the bandwidth required for file shipping. - Streaming replication (see ) + Streaming replication (see ) allows a much smaller window of data loss. @@ -547,7 +547,7 @@ protocol to make nodes agree on a serializable transactional order. rollforward will take considerably longer, so that technique only offers a solution for disaster recovery, not high availability. A standby server can also be used for read-only queries, in which case - it is called a Hot Standby server. See for + it is called a Hot Standby server. See for more information. @@ -585,7 +585,7 @@ protocol to make nodes agree on a serializable transactional order. associated with tablespaces will be passed across unmodified, so both primary and standby servers must have the same mount paths for tablespaces if that feature is used. Keep in mind that if - + 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 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. In standby mode, the server continuously applies WAL received from the master server. The standby server can read WAL from a WAL archive - (see ) or directly from the master + (see ) or directly from the master over a TCP connection (streaming replication). The standby server will also attempt to restore any WAL found in the standby cluster's pg_wal directory. That typically happens after a server @@ -657,7 +657,7 @@ protocol to make nodes agree on a serializable transactional order. Set up continuous archiving on the primary to an archive directory accessible from the standby, as described - in . The archive location should be + in . The archive location should be 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 the master server. @@ -676,7 +676,7 @@ protocol to make nodes agree on a serializable transactional order. - Take a base backup as described in + Take a base backup as described in to bootstrap the standby server. @@ -686,7 +686,7 @@ protocol to make nodes agree on a serializable transactional order. To set up the standby server, restore the base backup taken from primary - server (see ). Create a recovery + server (see ). Create a recovery command file recovery.conf in the standby's cluster data directory, and turn on standby_mode. Set restore_command 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 described here. restore_command should return immediately if the file does not exist; the server will retry the command again if - necessary. See + necessary. See for using tools like pg_standby. @@ -724,11 +724,11 @@ protocol to make nodes agree on a serializable transactional order. If you're using a WAL archive, its size can be minimized using the parameter to remove files that are no + linkend="archive-cleanup-command"/> parameter to remove files that are no longer required by the standby server. The pg_archivecleanup utility is designed specifically to be used with archive_cleanup_command in typical single-standby - configurations, see . + configurations, see . 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 backup, even if they're no longer needed by the standby. @@ -768,7 +768,7 @@ archive_cleanup_command = 'pg_archivecleanup /path/to/archive %r' Streaming replication is asynchronous by default - (see ), in which case there is + (see ), in which case there is a small delay between committing a transaction in the primary and the changes becoming visible in the standby. This delay is however much smaller than with file-based log shipping, typically under one second @@ -791,27 +791,27 @@ archive_cleanup_command = 'pg_archivecleanup /path/to/archive %r' To use streaming replication, set up a file-based log-shipping standby - server as described in . The step that + server as described in . The step that turns a file-based log-shipping standby into streaming replication standby is setting primary_conninfo setting in the recovery.conf file to point to the primary server. Set - and authentication options + and authentication options (see pg_hba.conf) on the primary so that the standby server can connect to the replication pseudo-database on the primary - server (see ). + server (see ). On systems that support the keepalive socket option, setting - , - and - helps the primary promptly + , + and + helps the primary promptly notice a broken connection. Set the maximum number of concurrent connections from the standby servers - (see for details). + (see for details). @@ -882,15 +882,15 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' standby. These locations can be retrieved using pg_current_wal_lsn on the primary and pg_last_wal_receive_lsn on the standby, - respectively (see and - for details). + respectively (see and + for details). The last WAL receive location in the standby is also displayed in the process status of the WAL receiver process, displayed using the - ps command (see for details). + ps command (see for details). You can retrieve a list of WAL sender processes via the - view. Large differences between + view. Large differences between pg_current_wal_lsn and the view's sent_lsn field might indicate that the master server is under heavy load, while differences between sent_lsn and @@ -899,7 +899,7 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' On a hot standby, the status of the WAL receiver process can be retrieved - via the view. A large + via the view. A large difference between pg_last_wal_replay_lsn and the view's received_lsn indicates that WAL is being received faster than it can be replayed. @@ -922,9 +922,9 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' In lieu of using replication slots, it is possible to prevent the removal - of old WAL segments using , or by + of old WAL segments using , or by storing the segments in an archive using - . + . However, these methods often result in retaining more WAL segments than required, whereas replication slots retain only the number of segments known to be needed. An advantage of these methods is that they bound @@ -932,8 +932,8 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' to do this using replication slots. - Similarly, - and provide protection against + Similarly, + and provide protection against relevant rows being removed by vacuum, but the former provides no 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 @@ -952,8 +952,8 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' Slots can be created and dropped either via the streaming replication - protocol (see ) or via SQL - functions (see ). + protocol (see ) or via SQL + functions (see ). @@ -1017,7 +1017,7 @@ primary_slot_name = 'node_a_slot' Cascading replication is currently asynchronous. Synchronous replication - (see ) settings have no effect on + (see ) settings have no effect on cascading replication at present. @@ -1034,7 +1034,7 @@ primary_slot_name = 'node_a_slot' To use cascading replication, set up the cascading standby so that it can accept replication connections (that is, set - and , + and , and configure host-based authentication). You will also need to set primary_conninfo in the downstream @@ -1109,11 +1109,11 @@ primary_slot_name = 'node_a_slot' Once streaming replication has been configured, configuring synchronous replication requires only one additional configuration step: - must be set to + must be set to a non-empty value. synchronous_commit must also be set to on, but since this is the default value, typically no change is - required. (See and - .) + required. (See and + .) This configuration will cause each commit to wait for confirmation that the standby has written the commit record to durable 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 must be recreated, either on the former primary system when it comes up, or on a third, - possibly new, system. The utility can be + possibly new, system. The utility can be used to speed up this process on large clusters. Once complete, the primary and standby can be 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 setup, set standby_mode off, because you are implementing the polling required for standby operation yourself. See the - module for a reference + module for a reference implementation of this. @@ -1551,7 +1551,7 @@ if (!triggered) A working example of a waiting restore_command is provided - in the module. It + in the module. It 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 configurations and environments. @@ -1592,17 +1592,17 @@ if (!triggered) Set up continuous archiving from the primary to a WAL archive directory on the standby server. Ensure that - , - and - + , + and + are set appropriately on the primary - (see ). + (see ). Make a base backup of the primary server (see ), and load this data onto the standby. + linkend="backup-base-backup"/>), and load this data onto the standby. @@ -1610,7 +1610,7 @@ if (!triggered) Begin recovery on the standby server from the local WAL archive, using a recovery.conf that specifies a restore_command that waits as described - previously (see ). + previously (see ). @@ -1644,7 +1644,7 @@ if (!triggered) An external program can call the pg_walfile_name_offset() - function (see ) + function (see ) 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 and copy the data from the last known end of WAL through the current end @@ -1663,7 +1663,7 @@ if (!triggered) Starting with PostgreSQL version 9.0, you can use - streaming replication (see ) to + streaming replication (see ) to achieve the same benefits with less effort. @@ -1697,7 +1697,7 @@ if (!triggered) User's Overview - When the parameter is set to true on a + When the parameter is set to true on a standby server, it will begin accepting connections once the recovery has brought the system to a consistent state. All such connections are 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 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 - level. For more details, see . + level. For more details, see . @@ -1891,7 +1891,7 @@ if (!triggered) Users will be able to tell whether their session is read-only by issuing SHOW transaction_read_only. In addition, a set of - functions () allow users to + functions () allow users to access information about the standby server. These allow you to write 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 @@ -1986,8 +1986,8 @@ if (!triggered) 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 WAL application is usually not desirable. So the cancel mechanism has - parameters, and , that define the maximum + parameters, and , that define the maximum allowed delay in WAL application. Conflicting queries will be canceled 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 @@ -2082,7 +2082,7 @@ if (!triggered) - Another option is to increase + Another option is to increase 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 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 It is important that the administrator select appropriate settings for - and . The best choices vary + and . The best choices vary depending on business priorities. For example if the server is primarily tasked as a High Availability server, then you will want low delay 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 Various parameters have been mentioned above in - and - . + and + . - On the primary, parameters and - can be used. - and - have no effect if set on + On the primary, parameters and + can be used. + and + have no effect if set on the primary. - On the standby, parameters , - and - can be used. - has no effect + On the standby, parameters , + and + can be used. + has no effect as long as the server remains in standby mode, though it will become relevant if the standby becomes primary. @@ -2452,8 +2452,8 @@ LOG: database system is ready to accept read only connections The Serializable transaction isolation level is not yet available in hot - standby. (See and - for details.) + standby. (See and + for details.) An attempt to set a transaction to the serializable isolation level in hot standby mode will generate an error. diff --git a/doc/src/sgml/history.sgml b/doc/src/sgml/history.sgml index b59e65bb20..59bfdb6055 100644 --- a/doc/src/sgml/history.sgml +++ b/doc/src/sgml/history.sgml @@ -31,12 +31,12 @@ Office (ARO), the National Science Foundation (NSF), and ESL, Inc. The implementation of POSTGRES began in 1986. The initial - concepts for the system were presented in , + concepts for the system were presented in , and the definition of the initial data model appeared in . The design of the rule system at that time was - described in . The rationale and + linkend="rowe87"/>. The design of the rule system at that time was + described in . The rationale and architecture of the storage manager were detailed in . + linkend="ston87b"/>. @@ -44,10 +44,10 @@ releases since then. The first demoware system became operational in 1987 and was shown at the 1988 ACM-SIGMOD Conference. Version 1, described in - , was released to a few external users in + , was released to a few external users in June 1989. In response to a critique of the first rule system - (), the rule system was redesigned (), and Version 2 was released in June 1990 with + (), the rule system was redesigned (), and Version 2 was released in June 1990 with the new rule system. Version 3 appeared in 1991 and added support for multiple storage managers, an improved query executor, and a rewritten rule system. For the most part, subsequent releases @@ -216,7 +216,7 @@ Details about what has happened in PostgreSQL since - then can be found in . + then can be found in . diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml index 0264e4e532..94ccd1201e 100644 --- a/doc/src/sgml/hstore.sgml +++ b/doc/src/sgml/hstore.sgml @@ -70,7 +70,7 @@ key => NULL constant, then any single-quote characters and (depending on the setting of the standard_conforming_strings configuration parameter) backslash characters need to be escaped correctly. See - for more on the handling of string + for more on the handling of string constants. @@ -87,8 +87,8 @@ key => NULL The operators provided by the hstore module are - shown in , the functions - in . + shown in , the functions + in .
@@ -629,7 +629,7 @@ ALTER TABLE tablename ALTER hstorecol TYPE hstore USING hstorecol || ''; extensions for PL/Python are called hstore_plpythonu, hstore_plpython2u, and hstore_plpython3u - (see for the PL/Python naming + (see for the PL/Python naming convention). If you use them, hstore values are mapped to Python dictionaries. diff --git a/doc/src/sgml/indexam.sgml b/doc/src/sgml/indexam.sgml index a94b188f22..a7f6c8dc6a 100644 --- a/doc/src/sgml/indexam.sgml +++ b/doc/src/sgml/indexam.sgml @@ -22,7 +22,7 @@ pages so that they can use the regular storage manager and buffer manager to access the index contents. (All the existing index access methods furthermore use the standard page layout described in , 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.) @@ -31,7 +31,7 @@ tuple identifiers, or TIDs, of row versions (tuples) in the index's parent table. A TID consists of a block number and an item number within that block (see ). This is sufficient + linkend="storage-page-layout"/>). This is sufficient information to fetch a particular row version from the table. 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 @@ -52,8 +52,8 @@ system catalog. The pg_am entry specifies a name and a handler function for the access method. These entries can be created and deleted using the - and - SQL commands. + and + SQL commands. @@ -71,7 +71,7 @@ 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 visible or callable at the SQL level. The support functions are described - in . + in . @@ -153,7 +153,7 @@ typedef struct IndexAmRoutine These entries allow the planner to determine what kinds of query qualifications can be used with indexes of this access method. Operator families and classes are described - in , which is prerequisite material for reading + in , which is prerequisite material for reading this chapter. @@ -177,7 +177,7 @@ typedef struct IndexAmRoutine Some of the flag fields of IndexAmRoutine have nonobvious implications. The requirements of amcanunique - are discussed in . + are discussed in . The amcanmulticol flag asserts that the access method supports multicolumn indexes, while amoptionalkey asserts that it allows scans @@ -271,7 +271,7 @@ aminsert (Relation indexRelation, amcanunique flag is true) then checkUnique indicates the type of uniqueness check to perform. This varies depending on whether the unique constraint is - deferrable; see for details. + deferrable; see for details. Normally the access method only needs the heapRelation parameter when performing uniqueness checking (since then it will have to look into the heap to verify tuple liveness). @@ -386,7 +386,7 @@ amcostestimate (PlannerInfo *root, double *indexCorrelation); Estimate the costs of an index scan. This function is described fully - in , below. + in , below. @@ -480,7 +480,7 @@ amvalidate (Oid opclassoid); The purpose of an index, of course, is to support scans for tuples matching an indexable WHERE condition, often called a qualifier or scan key. The semantics of - index scanning are described more fully in , + index scanning are described more fully in , below. An index access method can support plain index scans, bitmap index scans, or both. The scan-related functions that an index access method must or may provide are: @@ -594,7 +594,7 @@ amgetbitmap (IndexScanDesc scan, amgetbitmap and amgettuple cannot be used in the same index scan; there are other restrictions too when using amgetbitmap, as explained - in . + in . @@ -852,7 +852,7 @@ amparallelrescan (IndexScanDesc scan); index tuples. Finally, amgetbitmap does not guarantee any locking of the returned tuples, with implications - spelled out in . + spelled out in . @@ -901,7 +901,7 @@ amparallelrescan (IndexScanDesc scan); 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. This is okay because the index reader would be uninterested in an - uncommitted row anyway. But see .) + uncommitted row anyway. But see .) diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml index 248ed7e8eb..0818196e76 100644 --- a/doc/src/sgml/indices.sgml +++ b/doc/src/sgml/indices.sgml @@ -77,7 +77,7 @@ CREATE INDEX test1_id_index ON test1 (id); than a sequential table scan. But you might have to run the ANALYZE command regularly to update statistics to allow the query planner to make educated decisions. - See for information about + See for information about how to find out whether an index is used and when and why the planner might choose not to use an index. @@ -99,7 +99,7 @@ CREATE INDEX test1_id_index ON test1 (id); It is possible to allow writes to occur in parallel with index creation, but there are several caveats to be aware of — for more information see . + endterm="sql-createindex-concurrently-title"/>. @@ -161,7 +161,7 @@ CREATE INDEX test1_id_index ON test1 (id); col LIKE '%bar'. However, if your database does not use the C locale you will need to create the index with a special operator class to support indexing of pattern-matching queries; see - below. It is also possible to use + below. It is also possible to use B-tree indexes for ILIKE and ~*, but only if the pattern starts with non-alphabetic characters, i.e., characters that are not affected by @@ -226,13 +226,13 @@ CREATE INDEX name ON table && - (See for the meaning of + (See for the meaning of these operators.) The GiST operator classes included in the standard distribution are - documented in . + documented in . Many other GiST operator classes are available in the contrib collection or as separate - projects. For more information see . + projects. For more information see . @@ -244,7 +244,7 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10; 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. - In , operators that can be + In , operators that can be used in this way are listed in the column Ordering Operators. @@ -274,11 +274,11 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10; >^ - (See for the meaning of + (See for the meaning of these operators.) The SP-GiST operator classes included in the standard distribution are - documented in . - For more information see . + documented in . + For more information see . @@ -313,13 +313,13 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10; && - (See for the meaning of + (See for the meaning of these operators.) The GIN operator classes included in the standard distribution are - documented in . + documented in . Many other GIN operator classes are available in the contrib collection or as separate - projects. For more information see . + projects. For more information see . @@ -351,8 +351,8 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10; The BRIN operator classes included in the standard distribution are - documented in . - For more information see . + documented in . + For more information see . @@ -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. Indexes with more than three columns are unlikely to be helpful unless the usage of the table is extremely stylized. See also - and - for some discussion of the + and + for some discussion of the merits of different index configurations. @@ -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 multicolumn index on (x, y). This index would typically be more efficient than index combination for queries involving both - columns, but as discussed in , it + columns, but as discussed in , it would be almost useless for queries involving only y, so it should not be the only index. A combination of the multicolumn index and a separate index on y 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 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 - updated in all cases. shows a + updated in all cases. shows a possible application of this idea. @@ -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 index that the typical query workload is not interested in; this is shown in . This results in the same + linkend="indexes-partial-ex2"/>. This results in the same advantages as listed above, but it prevents the uninteresting values from being accessed via that index, even if an index scan might be profitable in that @@ -878,7 +878,7 @@ SELECT * FROM orders WHERE order_nr = 3501; - also illustrates that the + also illustrates that the indexed column and the column used in the predicate do not need to match. PostgreSQL supports partial 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 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 . This enforces uniqueness + linkend="indexes-partial-ex3"/>. This enforces uniqueness among the rows that satisfy the index predicate, without constraining those that do not. @@ -962,8 +962,8 @@ CREATE UNIQUE INDEX tests_success_constraint ON tests (subject, target) More information about partial indexes can be found in , , and . + linkend="ston89b"/>, , and . @@ -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 heap-access portion of an index scan thus involves a lot of random access into the heap, which can be slow, particularly on traditional - rotating media. (As described in , + rotating media. (As described in , bitmap scans try to alleviate this cost by doing the heap accesses in sorted order, but that only goes so far.) @@ -1212,7 +1212,7 @@ SELECT x FROM tab WHERE x = 'key' AND z < 42; is physically possible. But there is an additional requirement for any table scan in PostgreSQL: it must verify that each retrieved row be visible to the query's MVCC snapshot, as - discussed in . Visibility information is not stored + discussed in . Visibility information is not stored 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 indeed the case, if the table row has been modified recently. However, @@ -1289,7 +1289,7 @@ SELECT f(x) FROM tab WHERE f(x) < 1; Partial indexes also have interesting interactions with index-only scans. - Consider the partial index shown in : + Consider the partial index shown in : CREATE UNIQUE INDEX tests_success_constraint ON tests (subject, target) 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 which indexes are actually used by the real-life query workload. Examining index usage for an individual query is done with the - + command; its application for this purpose is - illustrated in . + illustrated in . It is also possible to gather overall statistics about index usage - in a running server, as described in . + in a running server, as described in . @@ -1343,7 +1343,7 @@ SELECT target FROM tests WHERE subject = 'some-subject' AND success; - Always run + Always run first. This command collects statistics about the distribution of the values in the 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 index usage without having run ANALYZE is therefore a lost cause. - See - and for more information. + See + and for more information. @@ -1386,7 +1386,7 @@ SELECT target FROM tests WHERE subject = 'some-subject' AND success; When indexes are not used, it can be useful for testing to force their use. There are run-time parameters that can turn off - various plan types (see ). + various plan types (see ). For instance, turning off sequential scans (enable_seqscan) and nested-loop joins (enable_nestloop), 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 the plan node. The costs estimated for the plan nodes can be adjusted via run-time parameters (described in ). + linkend="runtime-config-query-constants"/>). An inaccurate selectivity estimate is due to insufficient statistics. It might be possible to improve this by tuning the statistics-gathering parameters (see - ). + ). diff --git a/doc/src/sgml/information_schema.sgml b/doc/src/sgml/information_schema.sgml index 58c54254d7..99b0ea8519 100644 --- a/doc/src/sgml/information_schema.sgml +++ b/doc/src/sgml/information_schema.sgml @@ -579,7 +579,7 @@
- See also under , a similarly + See also under , a similarly structured view, for further information on some of the columns. @@ -776,7 +776,7 @@ sql_identifier The specific name of the function. See for more information. + linkend="infoschema-routines"/> for more information. @@ -895,7 +895,7 @@ identifies which character set the available collations are applicable to. In PostgreSQL, there is only one character set per database (see explanation - in ), so this view does + in ), so this view does not provide much useful information. @@ -1178,7 +1178,7 @@ that use data types owned by a currently enabled role. Note that in PostgreSQL, built-in data types behave like user-defined types, so they are included here as well. See - also for details. + also for details. @@ -3134,7 +3134,7 @@ ORDER BY c.ordinal_position; sql_identifier The specific name of the function. See for more information. + linkend="infoschema-routines"/> for more information. @@ -3594,7 +3594,7 @@ ORDER BY c.ordinal_position; sql_identifier The specific name of the function. See for more information. + linkend="infoschema-routines"/> for more information. @@ -3930,7 +3930,7 @@ ORDER BY c.ordinal_position; sql_identifier The specific name of the function. See for more information. + linkend="infoschema-routines"/> for more information. @@ -4762,7 +4762,7 @@ ORDER BY c.ordinal_position; The table sql_features contains information about which formal features defined in the SQL standard are supported by PostgreSQL. This is the - same information that is presented in . + same information that is presented in . There you can also find some additional background information. @@ -4998,7 +4998,7 @@ ORDER BY c.ordinal_position; The table sql_packages contains information about which feature packages defined in the SQL standard are supported by PostgreSQL. Refer to for background information on feature packages. + linkend="features"/> for background information on feature packages.
@@ -5586,7 +5586,7 @@ ORDER BY c.ordinal_position; sql_identifier The specific name of the function. See for more information. + linkend="infoschema-routines"/> for more information. @@ -5891,9 +5891,9 @@ ORDER BY c.ordinal_position; USAGE privileges granted on user-defined types to a 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 - composite types (see under + composite types (see under for why); see - for domain privileges. + for domain privileges.
@@ -6068,7 +6068,7 @@ ORDER BY c.ordinal_position; differentiate between these. Other user-defined types such as base types and enums, which are PostgreSQL extensions, are not shown here. For domains, - see instead. + see instead.
@@ -6522,7 +6522,7 @@ ORDER BY c.ordinal_position; sql_identifier The specific name of the function. See for more information. + linkend="infoschema-routines"/> for more information. diff --git a/doc/src/sgml/install-windows.sgml b/doc/src/sgml/install-windows.sgml index 029e1dbc28..99e9c7b78e 100644 --- a/doc/src/sgml/install-windows.sgml +++ b/doc/src/sgml/install-windows.sgml @@ -37,8 +37,8 @@ Building using MinGW or Cygwin uses the normal build system, see - and the specific notes in - and . + and the specific notes in + and . To produce native 64 bit binaries in these environments, use the tools from MinGW-w64. These tools can also be used to cross-compile for 32 bit and 64 bit Windows @@ -457,7 +457,7 @@ $ENV{CONFIG}="Debug"; For more information about the regression tests, see - . + . diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index f8e1d60356..a922819fce 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -54,7 +54,7 @@ su - postgres In general, a modern Unix-compatible platform should be able to run PostgreSQL. The platforms that had received specific testing at the - time of release are listed in + time of release are listed in below. In the doc subdirectory of the distribution there are several platform-specific FAQ documents you might wish to consult if you are having trouble. @@ -193,7 +193,7 @@ su - postgres required version is Python 2.4. Python 3 is supported if it's version 3.1 or later; but see - + when using Python 3. @@ -262,7 +262,7 @@ su - postgres To build the PostgreSQL documentation, there is a separate set of requirements; see - . + . @@ -358,7 +358,7 @@ su - postgres You can also get the source directly from the version control repository, see - . + . @@ -835,8 +835,8 @@ su - postgres Build with LDAPLDAP support for authentication and connection parameter lookup (see - and - for more information). On Unix, + and + for more information). On Unix, this requires the OpenLDAP package to be installed. On Windows, the default WinLDAP library is used. configure will check for the required @@ -855,7 +855,7 @@ su - postgres for systemdsystemd service notifications. This improves integration if the server binary is started under systemd but has no impact - otherwise; see for more + otherwise; see for more information. libsystemd and the associated header files need to be installed to be able to use this option. @@ -901,7 +901,7 @@ su - postgres - Build the module + Build the module (which provides functions to generate UUIDs), using the specified UUID library.UUID LIBRARY must be one of: @@ -968,7 +968,7 @@ su - postgres Use libxslt when building the - + module. xml2 relies on this library to perform XSL transformations of XML. @@ -1084,7 +1084,7 @@ su - postgres has no support for strong random numbers on the platform. A source of random numbers is needed for some authentication protocols, as well as some routines in the - + module. disables functionality that requires cryptographically strong random numbers, and substitutes a weak pseudo-random-number-generator for the generation of @@ -1188,7 +1188,7 @@ su - postgres code coverage testing instrumentation. When run, they generate files in the build directory with code coverage metrics. - See + See for more information. This option is for use only with GCC and when doing development work. @@ -1249,7 +1249,7 @@ su - postgres Compiles PostgreSQL with support for the dynamic tracing tool DTrace. - See + See for more information. @@ -1285,7 +1285,7 @@ su - postgres Enable tests using the Perl TAP tools. This requires a Perl installation and the Perl module IPC::Run. - See for more information. + See for more information. @@ -1442,7 +1442,7 @@ su - postgres whether Python 2 or 3 is specified here (or otherwise implicitly chosen) determines which variant of the PL/Python language becomes available. See - + for more information. @@ -1569,7 +1569,7 @@ PostgreSQL, contrib, and documentation successfully made. Ready to install. make check (This won't work as root; do it as an unprivileged user.) - See for + See for detailed information about interpreting the test results. You can repeat this test at any later time by issuing the same command. @@ -1581,7 +1581,7 @@ PostgreSQL, contrib, and documentation successfully made. Ready to install. If you are upgrading an existing system be sure to read - , + , which has instructions about upgrading a cluster. @@ -1593,7 +1593,7 @@ PostgreSQL, contrib, and documentation successfully made. Ready to install. make install This will install files into the directories that were specified - in . Make sure that you have appropriate + in . Make sure that you have appropriate permissions to write into that area. Normally you need to do this step as root. Alternatively, you can create the target 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 Replace /usr/local/pgsql/lib with whatever you set - to in . + to in . You should put these commands into a shell start-up file such as /etc/profile or ~/.bash_profile. Some 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 /usr/local/pgsql or some other location that is not searched for programs by default, you should add /usr/local/pgsql/bin (or whatever you set - to in ) + to in ) into your PATH. Strictly speaking, this is not necessary, but it will make the use of PostgreSQL much more convenient. @@ -1873,7 +1873,7 @@ export MANPATH Other Unix-like systems may also work but are not currently being tested. In most cases, all CPU architectures supported by a given operating system will work. Look in - below to see if + below to see if there is information specific to your operating system, particularly if using an older system. @@ -1895,8 +1895,8 @@ export MANPATH This section documents additional platform-specific issues regarding the installation and setup of PostgreSQL. Be sure to read the installation instructions, and in - particular as well. Also, - check regarding the + particular as well. Also, + check regarding the interpretation of regression test results. @@ -2247,7 +2247,7 @@ ERROR: could not load library "/opt/dbs/pgsql/lib/plperl.so": Bad address PostgreSQL can be built using Cygwin, a Linux-like environment for Windows, but that method is inferior to the native Windows build - (see ) and + (see ) and running a server under Cygwin is no longer recommended. @@ -2441,7 +2441,7 @@ PHSS_30849 s700_800 u2comp/be/plugin library Patch Microsoft's Visual C++ compiler suite. The MinGW build variant uses the normal build system described in this chapter; the Visual C++ build works completely differently - and is described in . + and is described in . It is a fully native build and uses no additional software like MinGW. A ready-made installer is available on the main PostgreSQL web site. @@ -2602,7 +2602,7 @@ LIBOBJS = snprintf.o Using DTrace for Tracing PostgreSQL - Yes, using DTrace is possible. See for + Yes, using DTrace is possible. See for further information. diff --git a/doc/src/sgml/intarray.sgml b/doc/src/sgml/intarray.sgml index 0cf9d5f3f6..b633cf3677 100644 --- a/doc/src/sgml/intarray.sgml +++ b/doc/src/sgml/intarray.sgml @@ -29,8 +29,8 @@ The functions provided by the intarray module - are shown in , the operators - in . + are shown in , the operators + in .
diff --git a/doc/src/sgml/intro.sgml b/doc/src/sgml/intro.sgml index 2fb19725f0..3038826311 100644 --- a/doc/src/sgml/intro.sgml +++ b/doc/src/sgml/intro.sgml @@ -23,13 +23,13 @@ - is an informal introduction for new users. + is an informal introduction for new users. - documents the SQL query + documents the SQL query language environment, including data types and functions, as well as user-level performance tuning. Every PostgreSQL user should read this. @@ -38,7 +38,7 @@ - describes the installation and + describes the installation and administration of the server. Everyone who runs a PostgreSQL server, be it for private use or for others, should read this part. @@ -47,7 +47,7 @@ - describes the programming + describes the programming interfaces for PostgreSQL client programs. @@ -56,7 +56,7 @@ - contains information for + contains information for advanced users about the extensibility capabilities of the server. Topics include user-defined data types and functions. @@ -65,7 +65,7 @@ - contains reference information about + contains reference information about SQL commands, client and server programs. This part supports the other parts with structured information sorted by command or program. @@ -74,7 +74,7 @@ - contains assorted information that might be of + contains assorted information that might be of use to PostgreSQL developers. diff --git a/doc/src/sgml/isn.sgml b/doc/src/sgml/isn.sgml index 329b7b2c54..34d37ede01 100644 --- a/doc/src/sgml/isn.sgml +++ b/doc/src/sgml/isn.sgml @@ -25,7 +25,7 @@ Data Types - shows the data types provided by + shows the data types provided by the isn module. @@ -222,7 +222,7 @@ The isn module provides the standard comparison operators, plus B-tree and hash indexing support for all these data types. In - addition there are several specialized functions; shown in . + addition there are several specialized functions; shown in . In this table, isn means any one of the module's data types. diff --git a/doc/src/sgml/json.sgml b/doc/src/sgml/json.sgml index 05ecef2ffc..731b469613 100644 --- a/doc/src/sgml/json.sgml +++ b/doc/src/sgml/json.sgml @@ -18,7 +18,7 @@ the JSON data types have the advantage of enforcing that each stored value is valid according to the JSON rules. There are also assorted JSON-specific functions and operators available for data stored - in these data types; see . + in these data types; see . @@ -82,7 +82,7 @@ Many of the JSON processing functions described - in will convert Unicode escapes to + in will convert Unicode escapes to regular characters, and will therefore throw the same types of errors just described even if their input is of type json not jsonb. The fact that the json input function does @@ -98,7 +98,7 @@ When converting textual JSON input into jsonb, the primitive types described by RFC 7159 are effectively mapped onto native PostgreSQL types, as shown - in . + in . Therefore, there are some minor additional constraints on what constitutes valid jsonb data that do not apply to the json type, nor to JSON in the abstract, corresponding @@ -380,7 +380,7 @@ SELECT doc->'site_name' FROM websites The various containment and existence operators, along with all other JSON operators and functions are documented - in . + in . @@ -404,7 +404,7 @@ SELECT doc->'site_name' FROM websites and ?| operators and path/value-exists operator @>. (For details of the semantics that these operators - implement, see .) + implement, see .) An example of creating an index with this operator class is: CREATE INDEX idxgin ON api USING GIN (jdoc); @@ -465,7 +465,7 @@ CREATE INDEX idxgintags ON api USING GIN ((jdoc -> 'tags')); operator ? to the indexed expression jdoc -> 'tags'. (More information on expression indexes can be found in .) + linkend="indexes-expressional"/>.) Another approach to querying is to exploit containment, for example: diff --git a/doc/src/sgml/keywords.sgml b/doc/src/sgml/keywords.sgml index 01bc9b47b1..2dba7adedf 100644 --- a/doc/src/sgml/keywords.sgml +++ b/doc/src/sgml/keywords.sgml @@ -9,10 +9,10 @@ - lists all tokens that are key words + lists all tokens that are key words in the SQL standard and in PostgreSQL &version;. Background information can be found in . + linkend="sql-syntax-identifiers"/>. (For space reasons, only the latest two versions of the SQL standard, and SQL-92 for historical comparison, are included. The differences between those and the other intermediate standard versions are small.) @@ -45,7 +45,7 @@ - In in the column for + In in the column for PostgreSQL we classify as non-reserved those key words that are explicitly known to the parser but are allowed as column or table names. @@ -69,7 +69,7 @@ It is important to understand before studying that the fact that a key word is not + linkend="keywords-table"/> that the fact that a key word is not reserved in PostgreSQL does not mean that the feature related to the word is not implemented. Conversely, the presence of a key word does not indicate the existence of a feature. diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 694921f212..4703309254 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -25,15 +25,15 @@ those written for C++, Perl, Python, Tcl and ECPG. So some aspects of libpq's behavior will be important to you if you use one of those packages. In particular, - , - and - + , + and + describe behavior that is visible to the user of any application that uses libpq. - Some short programs are included at the end of this chapter () to show how + Some short programs are included at the end of this chapter () to show how to write programs that use libpq. There are also several complete examples of libpq applications in the directory src/test/examples in the source code distribution. @@ -118,7 +118,7 @@ PGconn *PQconnectdbParams(const char * const *keywords, The currently recognized parameter key words are listed in - . + . @@ -128,7 +128,7 @@ PGconn *PQconnectdbParams(const char * const *keywords, dbname is expanded this way, any subsequent dbname value is processed as plain database name. More details on the possible connection string formats appear in - . + . @@ -140,7 +140,7 @@ PGconn *PQconnectdbParams(const char * const *keywords, If any parameter is NULL or an empty string, the corresponding - environment variable (see ) is checked. + environment variable (see ) is checked. If the environment variable is not set either, then the indicated built-in defaults are used. @@ -176,7 +176,7 @@ PGconn *PQconnectdb(const char *conninfo); The passed string can be empty to use all default parameters, or it can contain one or more parameter settings separated by whitespace, or it can contain a URI. - See for details. + See for details. @@ -289,7 +289,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn); The hostaddr and host parameters are used appropriately to ensure that name and reverse name queries are not made. See the documentation of - these parameters in for details. + these parameters in for details. @@ -802,7 +802,7 @@ host=localhost port=5432 dbname=mydb connect_timeout=10 The recognized parameter key words are listed in . + linkend="libpq-paramkeywords"/>. @@ -847,7 +847,7 @@ postgresql:///mydb?host=localhost&port=5433 Any connection parameters not corresponding to key words listed in are ignored and a warning message about them + linkend="libpq-paramkeywords"/> are ignored and a warning message about them is sent to stderr. @@ -867,7 +867,7 @@ postgresql://[2001:db8::1234]/database The host component is interpreted as described for the parameter . 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 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 @@ -954,7 +954,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname A comma-separated list of host names is also accepted, in which case each host name in the list is tried in order. See - for details. + for details. @@ -1006,13 +1006,13 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname is not the name of the server at network address hostaddr. Also, note that host rather than hostaddr is used to identify the connection in a password file (see - ). + ). A comma-separated list of hostaddrs is also accepted, in which case each host in the list is tried in order. See - for details. + for details. Without either a host name or host address, @@ -1044,7 +1044,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname The database name. Defaults to be the same as the user name. In certain contexts, the value is checked for extended - formats; see for more details on + formats; see for more details on those. @@ -1075,7 +1075,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname Specifies the name of the file used to store passwords - (see ). + (see ). Defaults to ~/.pgpass, or %APPDATA%\postgresql\pgpass.conf on Microsoft Windows. (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 (\); write \\ to represent a literal backslash. For a detailed discussion of the available - options, consult . + options, consult . @@ -1134,7 +1134,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname application_name - Specifies a value for the + Specifies a value for the configuration parameter. @@ -1145,7 +1145,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname Specifies a fallback value for the configuration parameter. + linkend="guc-application-name"/> configuration parameter. This value will be used if no value has been given for application_name via a connection parameter or the PGAPPNAME environment variable. Specifying @@ -1295,7 +1295,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname - See for a detailed description of how + See for a detailed description of how these options work. @@ -1430,7 +1430,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname to ensure that you are connected to a server run by a trusted user.) This option is only supported on platforms for which the peer authentication method is implemented; see - . + . @@ -1442,7 +1442,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname Kerberos service name to use when authenticating with GSSAPI. This must match the service name specified in the server configuration for Kerberos authentication to succeed. (See also - .) + .) @@ -1465,7 +1465,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname Service name to use for additional parameters. It specifies a service name in pg_service.conf that holds additional connection parameters. This allows applications to specify only a service name so connection parameters - can be centrally maintained. See . + can be centrally maintained. See . @@ -2225,7 +2225,7 @@ PGresult *PQexec(PGconn *conn, const char *command); PQexec call are processed in a single transaction, unless there are explicit BEGIN/COMMIT commands included in the query string to divide it into multiple - transactions. (See + transactions. (See for more details about how the server handles multi-query strings.) Note however that the returned PGresult structure describes only the result @@ -2447,7 +2447,7 @@ PGresult *PQprepare(PGconn *conn, PQprepare creates a prepared statement for later execution with PQexecPrepared. This feature allows commands to be executed repeatedly without being parsed and - planned each time; see for details. + planned each time; see for details. PQprepare is supported only in protocol 3.0 and later connections; it will fail when using protocol 2.0. @@ -2489,10 +2489,10 @@ PGresult *PQprepare(PGconn *conn, Prepared statements for use with PQexecPrepared can also - be created by executing SQL + be created by executing SQL statements. Also, although there is no libpq function for deleting a prepared statement, the SQL statement + linkend="sql-deallocate"/> statement can be used for that purpose. @@ -2746,7 +2746,7 @@ ExecStatusType PQresultStatus(const PGresult *res); The PGresult contains a single result tuple from the current command. This status occurs only when single-row mode has been selected for the query - (see ). + (see ). @@ -2770,7 +2770,7 @@ ExecStatusType PQresultStatus(const PGresult *res); never be returned directly by PQexec or other query execution functions; results of this kind are instead passed to the notice processor (see ). + linkend="libpq-notice-processing"/>). @@ -2941,7 +2941,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); front-end applications to perform specific operations (such as error handling) in response to a particular database error. For a list of the possible SQLSTATE codes, see . This field is not localizable, + linkend="errcodes-appendix"/>. This field is not localizable, and is always present. @@ -3118,7 +3118,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode); 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; see . Do not assume that + types; see . Do not assume that the presence of any of these fields guarantees the presence of another field. Core error sources observe the interrelationships noted above, but user-defined functions may use these fields in other @@ -4075,7 +4075,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn, bytea literal in an SQL statement. PQescapeByteaConn escapes bytes using either hex encoding or backslash escaping. See for more information. + linkend="datatype-binary"/> for more information. @@ -4508,7 +4508,7 @@ PGresult *PQgetResult(PGconn *conn); Another frequently-desired feature that can be obtained with PQsendQuery and PQgetResult is retrieving large query results a row at a time. This is discussed - in . + in . @@ -4600,14 +4600,14 @@ int PQisBusy(PGconn *conn); PQgetResult if PQisBusy returns false (0). It can also call PQnotifies to detect NOTIFY messages (see ). + linkend="libpq-notify"/>). A client that uses PQsendQuery/PQgetResult can also attempt to cancel a command that is still being processed - by the server; see . But regardless of + by the server; see . But regardless of the return value of PQcancel, the application must continue with the normal result-reading sequence using PQgetResult. A successful cancellation will @@ -4753,7 +4753,7 @@ int PQflush(PGconn *conn); (or a sibling function). This mode selection is effective only for the currently executing query. Then call PQgetResult repeatedly, until it returns null, as documented in . If the query returns any rows, they are returned + linkend="libpq-async"/>. If the query returns any rows, they are returned as individual PGresult objects, which look like normal query results except for having status code PGRES_SINGLE_TUPLE instead of @@ -5119,7 +5119,7 @@ typedef struct pgNotify - gives a sample program that illustrates + gives a sample program that illustrates the use of asynchronous notification. @@ -5242,7 +5242,7 @@ typedef struct pgNotify 0 indicates the overall copy format is textual (rows separated by newlines, columns separated by separator characters, etc). 1 indicates the overall copy format is binary. See for more information. + linkend="sql-copy"/> for more information. @@ -5322,7 +5322,7 @@ int PQputCopyData(PGconn *conn, into buffer loads of any convenient size. Buffer-load boundaries have no semantic significance when sending. The contents of the data stream must match the data format expected by the - COPY command; see for details. + COPY command; see for details. @@ -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 algorithm is NULL, this function will query the server for the current value of the - setting. That can block, and + setting. That can block, and will fail if the current transaction is aborted, or if the connection is busy executing another query. If you wish to use the default algorithm for the server but want to avoid blocking, query @@ -6072,7 +6072,7 @@ PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); Fires a PGEVT_RESULTCREATE event (see ) for each event procedure registered in the + linkend="libpq-events"/>) for each event procedure registered in the PGresult object. Returns non-zero for success, zero if any event procedure fails. @@ -7004,7 +7004,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGHOST PGHOST behaves the same as the connection parameter. + linkend="libpq-connect-host"/> connection parameter. @@ -7014,7 +7014,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGHOSTADDR PGHOSTADDR behaves the same as the connection parameter. + linkend="libpq-connect-hostaddr"/> connection parameter. This can be set instead of or in addition to PGHOST to avoid DNS lookup overhead. @@ -7026,7 +7026,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGPORT PGPORT behaves the same as the connection parameter. + linkend="libpq-connect-port"/> connection parameter. @@ -7036,7 +7036,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGDATABASE PGDATABASE behaves the same as the connection parameter. + linkend="libpq-connect-dbname"/> connection parameter. @@ -7046,7 +7046,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGUSER PGUSER behaves the same as the connection parameter. + linkend="libpq-connect-user"/> connection parameter. @@ -7056,12 +7056,12 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGPASSWORD PGPASSWORD behaves the same as the connection parameter. + linkend="libpq-connect-password"/> connection parameter. Use of this environment variable is not recommended for security reasons, as some operating systems allow non-root users to see process environment variables via ps; instead consider using a password file - (see ). + (see ). @@ -7071,7 +7071,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGPASSFILE PGPASSFILE behaves the same as the connection parameter. + linkend="libpq-connect-passfile"/> connection parameter. @@ -7081,7 +7081,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSERVICE PGSERVICE behaves the same as the connection parameter. + linkend="libpq-connect-service"/> connection parameter. @@ -7093,7 +7093,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSERVICEFILE specifies the name of the per-user connection service file. If not set, it defaults to ~/.pg_service.conf - (see ). + (see ). @@ -7103,7 +7103,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGOPTIONS PGOPTIONS behaves the same as the connection parameter. + linkend="libpq-connect-options"/> connection parameter. @@ -7113,7 +7113,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGAPPNAME PGAPPNAME behaves the same as the connection parameter. + linkend="libpq-connect-application-name"/> connection parameter. @@ -7123,7 +7123,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLMODE PGSSLMODE behaves the same as the connection parameter. + linkend="libpq-connect-sslmode"/> connection parameter. @@ -7133,7 +7133,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIRESSL PGREQUIRESSL behaves the same as the connection parameter. + linkend="libpq-connect-requiressl"/> connection parameter. This environment variable is deprecated in favor of the PGSSLMODE variable; setting both variables suppresses the effect of this one. @@ -7146,7 +7146,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLCOMPRESSION PGSSLCOMPRESSION behaves the same as the connection parameter. + linkend="libpq-connect-sslcompression"/> connection parameter. @@ -7156,7 +7156,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLCERT PGSSLCERT behaves the same as the connection parameter. + linkend="libpq-connect-sslcert"/> connection parameter. @@ -7166,7 +7166,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLKEY PGSSLKEY behaves the same as the connection parameter. + linkend="libpq-connect-sslkey"/> connection parameter. @@ -7176,7 +7176,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLROOTCERT PGSSLROOTCERT behaves the same as the connection parameter. + linkend="libpq-connect-sslrootcert"/> connection parameter. @@ -7186,7 +7186,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGSSLCRL PGSSLCRL behaves the same as the connection parameter. + linkend="libpq-connect-sslcrl"/> connection parameter. @@ -7196,7 +7196,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGREQUIREPEER PGREQUIREPEER behaves the same as the connection parameter. + linkend="libpq-connect-requirepeer"/> connection parameter. @@ -7206,7 +7206,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGKRBSRVNAME PGKRBSRVNAME behaves the same as the connection parameter. + linkend="libpq-connect-krbsrvname"/> connection parameter. @@ -7216,7 +7216,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGGSSLIB PGGSSLIB behaves the same as the connection parameter. + linkend="libpq-connect-gsslib"/> connection parameter. @@ -7226,7 +7226,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough) PGCONNECT_TIMEOUT PGCONNECT_TIMEOUT behaves the same as the connection parameter. + linkend="libpq-connect-connect-timeout"/> connection parameter. @@ -7236,7 +7236,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)